UnionPay

Overview - UnionPay

With more than 7.5 billion cards issued globally, UnionPay (also known as China UnionPay and its subsidiary, UnionPay International), is the largest card network in the world and the most commonly accepted payment method in mainland China. This card base opens up a huge opportunity for merchants to sell to consumers across more than 50 UnionPay card-issuing countries.

The UnionPay mobile app supports QR code payments and is available to residents of China, Hong Kong and Macau. The app has over 240 million registered users and 50 million monthly active users. UnionPay QR code payments are also supported by 28 additional banking/mobile apps within and outside of China, Hong Kong and Macau. With 42% of mainland Chinese consumers shopping cross-border, merchants accepting UnionPay QR code payments can open up business growth opportunities in the second-largest economy in the world.

Customer Experience - UnionPay

Step	Description	Image
1	Choose UnionPay.
2	Click Pay.
3	Redirect to Union Pay.
4	Proceed on the Union Pay page, enter card details and confirm payment.

Note: This customer experience is valid for a live environment. In a test environment, the customer experience may look different.

PayEngine Details - UnionPay

General

Name	Details
Product	Union Pay
Channels	ECOM
Currencies	AUD, CAD, CHF, CNY, EUR, GBP, HKD, JPY, NZD, SGD, USD
Countries	AE, AG, AT, AU, AZ, BD, BE, BN, BY, CA, CN, DE, ES, FI, FR, GB, GE, HK, HU, ID, IE, IT, JP, KE, KG, KH, KR, KZ, LB, LI, LK, LT, LU, MG, MN, MO, MT, MU, MX, MY, NL, NP, NZ, PA, PF, PH, PT, RU, SC, SG, SI, SK, SR, TH, TJ, TZ, US, VN
Technical Flow	Asynchronous
Recurring	No
Chargebacks	No
B2B applicable	No

Supported Features and Services

Name	Details
Debit	Yes
Preauthorization	No
Cancelation	No
Capture	No
Refunds	Yes
Notifications	Yes (webhook and email)
Settlement Reporting	Yes (Unified Settlement Reporting)

Integration Types

Name	Details
API	Yes
Widget	Yes
Bridge	No
Shop Plugin	No
Paylink	No

Integration via API - UnionPay

Technical Flow

Webhook and email notifications

At the time of the redirect, it is still uncertain whether a transaction will be completed successfully or not. Therefore, Payengine awaits for the final asynchronous notification before the status of a DEBIT transaction is changed from PENDING to SUCCESS or FAILURE.

A merchant should register for Payengine's notifications to receive this final status update.

Alternatively, a GET request on the order or DEBIT transaction would also work, but it is not ensured that the final status will be available immediately after the redirect and a merchant might have to query the GET multiple times.

Therefore, it is strongly recommended that Payengine's asynchronous notifications are used instead.

Merchants could receive notifications via URL (webhook) or email.

The notifications could be subscribed:

via the payengine API (link to API documentation)
via the Payengine Merchant Center (link to Merchant Center notifications documentation)

Specifications - UnionPay

Input Parameters for Authorizing Transactions

Parameter	Mandatory/Optional (M/O)	Description	Example
async.cancelUrl	M	Redirect URL when payment is cancelled	string	http://my.shop.com/cancel
async.failureUrl	M	Redirect URL for unsuccessful payment	string	http://my.shop.com/fail
async.successUrl	M	Redirect URL for successful payment	string	http://my.shop.com/success
payment.countryCode	O	Country code	string	The default value for the parameter payment.countryCode is CN if there is no extra country code provided. The default value in the widget is CN.
payment.accountHolder	O	The Union Pay accountholder name	string	Dr. Hans-Peter Meier

Samples

Debit transaction

POST /{{publicApiUrl}}/v1/orders/debit

Create Debit Request

{
    "product": "union-pay",
    "terms": 1468590412476,
    "privacy": 1468590412476,

Create Debit Response

{
    "createdAt": 1627654176516,
    "modifiedAt": 1627654176569,
    "merchantId": "Merchant-11111111-1111-1111-1111-111111111111",

Refund transaction

POST /{{publicApiUrl}}/{{apiVersion}}/orders/{{orderId}}/transactions/{{transactionId}}/refund

Create Refund Request

{
    "description": "description for transaction.",
    "initialAmount": 6060,
    "currency": "EUR",

Create Refund Response

{
    "createdAt": 1627654236389,
    "modifiedAt": 1627654236438,
    "type": "REFUND",

Testing

Union Pay can be tested via the Payengine Simulator.

The simulator should map the following functionalities:

debit payment
refund

The testing amounts for the two scenarios can be found below:

Result	Description
Success	Any applicable amount (excluding failure amounts listed below). The transaction's status changes from OK to SUCCESS.
Failure	Each of the amounts listed below: 11111 (€111,11) 111 (€1,11) The transaction's status changes from "OK" to "FAILURE".