📘
"paymentMethodName": "AliPay", "WeChat", "UnionPay"

Payment Method Features

Feature	AliPay	WeChat	UnionPay
Country	China	China	China
"paymentMethodName" in API	AliPay	WeChat	UnionPay
Processing Currencies	CNY, GBP, USD, EUR, HKD	CNY, GBP, USD, EUR, HKD	CNY, GBP, USD, EUR, HKD, SGD
Payments	Yes	Yes	Yes
-- Authentication	None	None	None
-- Min per transaction amount	0.01 CNY	--	--
-- Max per transaction amount	Vary, depends on your contract	50,000 USD	--
Disbursements	No	No	No
Refunds	Yes	Yes	Yes
-- Partial Refund	Yes	Yes	Yes
-- Multiple Partial Refunds	No	No	No
Chargebacks	No	No	No

Possible Payment Scenarios:

Our API will provide you with all the necessary information to execute on of the following scenarios:

Name	Steps
Displaying a QR Code in a Web Browser	The client requests a payment link. The system returns a QR payload (data for rendering the QR code). The client renders the QR code on the page. The end user scans the QR code using a mobile device and is redirected to the payment page or to the app (depend on the platform and installed application). The payment status is returned via a callback.
Payment via Mobile Application	The client requests a payment link. The system returns an url (payment link). The client either displays the url or redirects the user to it. The user completes the payment in payment link via browser or app (depends on the platform and installed application) The payment status is returned via a callback

Name

Steps

Displaying a QR Code in a Web Browser

The client requests a payment link.
The system returns a QR payload (data for rendering the QR code).
The client renders the QR code on the page.
The end user scans the QR code using a mobile device and is redirected to the payment page or to the app (depend on the platform and installed application).

The payment status is returned via a callback.

Payment via Mobile Application

The client requests a payment link.
The system returns an url (payment link).
The client either displays the url or redirects the user to it.
The user completes the payment in payment link via browser or app (depends on the platform and installed application)

The payment status is returned via a callback

Alipay, WeChat, UnionPay Payment & Refund Workflow

High-resolution image is available on the link: AliPay_WeChat_UnionPay.jpg

Section “QR Generation”

[Step 1.3] You need to create a new intent

Use the following API method to create an intent: *POST /processing/api/v1/intents*.
When creating the intent, complete the Payment object.
Most fields are common across all payment methods and are thoroughly described in the API Reference section.
Method-specific parameters ( please make sure you provided them correctly):

Payment method	Difference	Request parameters
AliPay App	On Desktop browser, after selecting Alipay as a payment method merchant checkout, a QR code appears. The shopper then opens Alipay app on their mobile phone and scans the barcode displayed on the browser page to complete the payment.	`"paymentMethodName" : "AliPay"` `"incomingDetails": {"terminalType"="APP", "os_type" = "IOS"/"ANDROID"}`
AliPay Web	On the mobile browser, a shopper selects Alipay as a payment method on Merchant checkout, and as redirected from the browser into the Alipay app to complete the payment before being redirected back to the Merchant browser.	`"paymentMethodName" : "AliPay"` `"incomingDetails": {"terminalType" = "WEB"}`
WeChat	On Desktop browser, after selecting WeChatPay as a payment method merchant checkout, a QR code appears. The shopper then opens WeChat app on their mobile phone and scans the barcode displayed on the browser page to complete the payment.	`"paymentMethodName" : "WeChat"` `"incomingDetails": {"terminal_type" = "WEB", "clientIp"=""}`
UnionPay	Using unionpay, customers pay by redirecting from your website or app, finish the payment, then return to your website or app where you get immediate notification on whether the payment succeeds or fails.	`"paymentMethodName" : "UnionPay"`

Ensure these all the required fields are completed accurately so that we can process your request correctly.

Request Example

{
    "clientReferenceId": "1234",
    "payments": [
        {
            "payer": {
                "countryIsoCode": "USD"
            },
            "paymentInstrument": {
                "paymentMethodName": "AliPay",
                "incomingDetails": {
                    "returnUrl": "",
                    "terminalType": "APP",
                    "os_type": "IOS",
                    "clientIp": "clientIp"
                }
            },
            "description": "Purchase description",
            "webhookUrl": "webhookUrl",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authCurrencyCode": "CNY"
        }
    ]
}

{
    "clientReferenceId": "1234",
    "payments": [
        {
            "payer": {
                "countryIsoCode": "USD"
            },
            "paymentInstrument": {
                "paymentMethodName": "AliPay",
                "incomingDetails": {
                    "returnUrl": "",
                    "terminalType": "WEB"
                }
            },
            "description": "Purchase description",
            "webhookUrl": "webhookUrl",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authCurrencyCode": "CNY"
        }
    ]
}

{
    "clientReferenceId": "1234",
    "payments": [
        {
            "payer": {
                "countryIsoCode": "USD"
            },
            "paymentInstrument": {
                "paymentMethodName": "WeChat",
                "incomingDetails": {
                    "returnUrl": "",
                    "terminalType": "WEB",
                    "clientIp": "clientIp"
                }
            },
            "description": "Purchase description",
            "webhookUrl": "webhookUrl",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authCurrencyCode": "CNY"
        }
    ]
}

{
    "clientReferenceId": "1234",
    "payments": [
        {
            "payer": {
                "countryIsoCode": "USD"
            },
            "paymentInstrument": {
                "paymentMethodName": "UnionPay",
                "incomingDetails": {
                    "returnUrl": ""
                }
            },
            "description": "Purchase description",
            "webhookUrl": "webhookUrl",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authCurrencyCode": "CNY"
        }
    ]
}

Fields description

Field	Required	Type	Description	Example
clientReferenceId	Required	String	The client/merchant intent reference. Aka, Transaction Reference	1234
payments	Required	Array	The list of payments	n/a
-- payer	Required	Object	The payer details	n/a
---- countryIsoCode	Required	String	Payer’s country of residence in ISO 3166-1 alpha-2 format	RU
-- paymentInstrument	Required	Object	The receiver payment instrument	n/a
---- paymentMethodName	Required	String	Payment method name	AliPay
---- incomingDetails	Required	Object	Additional data related to payment method	n/a
------ returnUrl	Required	String	The URL on the Merchant’s side to which the Payer is redirected upon completion of the Operation, instead of being shown the default receipt page
------ terminalType	Conditional	String	Depending on the payment method and the scenario, this parameter may be required and its value may differ.	WEB
------ os_type	Conditional	String	os_type is required if terminal_type is "APP" and paymentMethodName is "AliPay"	"IOS"/"ANDROID"
------ clientIp	Conditional	String	Client IP is required if paymentMethodName is "WeChat"
-- description	Required	String	The payment description (arbitrary string)	Purchase description
-- webhookUrl	Optional	String	The URL to which the payment charge state changes will be notified	webhookUrl
-- submittedAmount	Required	Object		n/a
---- submittedAmount.value	Required	Number	Transaction amount	100.40
---- currency	Required	String	The original currency of the transaction. Can vary, will be converted into auth currency during the processing	USD
-- authCurrencyCode	Required	String	The currency the transaction will be processed. Always CNY for this method	CNY

[Step 1.7] Return the QR/URL in response

In the response, you will receive an additional object payments.additionalData. It contains the following fields**:**
- QR_BASE64 – a QR code encoded in Base64
- redirectUrl – a URL to which the user should be redirected to complete the payment

Response Example

{
    "intentId": "232510340021612544",
    "payments": [
        {
            "id": "232510340646563840",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authAmount": {
                "value": 100.05,
                "currency": "CNY"
            },
            "payer": {
                "countryIsoCode": "CNY"
            },
            "paymentInstrument": {
                "id": "PI204264628196626432",
                "paymentMethodId": "PM199507277233246209",
                "paymentMethodName": "AliPay",
                "storedDetails": {
                    "returnUrl": "",
                    "terminalType": "APP",
                    "os_type": "IOS",
                    "clientIp": "clientIp"
                }
            },
            "status": "ACCEPTED",
            "additionalData": {
                "qrBase64": "qrBase64",
                "redirectUrl": "url"
            }
        }
    ],
    "disbursements": [],
    "clientReferenceIntentId": "123456789",
    "paymentCreationErrors": [],
    "disbursementCreationErrors": [],
    "intentStatus": "CREATED"
}

{
    "intentId": "232510340021612544",
    "payments": [
        {
            "id": "232510340646563840",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authAmount": {
                "value": 100.05,
                "currency": "CNY"
            },
            "payer": {
                "countryIsoCode": "CNY"
            },
            "paymentInstrument": {
                "id": "PI204264628196626432",
                "paymentMethodId": "PM199507277233246209",
                "paymentMethodName": "AliPay",
                "storedDetails": {
                    "returnUrl": "",
                    "terminalType": "WEB"
                }
            },
            "status": "ACCEPTED",
            "additionalData": {
                "qrBase64": "qrBase64",
                "url": "url"
            }
        }
    ],
    "disbursements": [],
    "clientReferenceIntentId": "123456789",
    "paymentCreationErrors": [],
    "disbursementCreationErrors": [],
    "intentStatus": "CREATED"
}

{
    "intentId": "232510340021612544",
    "payments": [
        {
            "id": "232510340646563840",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authAmount": {
                "value": 100.05,
                "currency": "CNY"
            },
            "payer": {
                "countryIsoCode": "CNY"
            },
            "paymentInstrument": {
                "id": "PI204264628196626432",
                "paymentMethodId": "PM199507277233246209",
                "paymentMethodName": "WeChat",
                "storedDetails": {
                    "returnUrl": "",
                    "terminalType": "WEB",
                    "clientIp": "clientIp"
                }
            },
            "status": "ACCEPTED",
            "additionalData": {
                "qrBase64": "qrBase64",
                "url": "url"
            }
        }
    ],
    "disbursements": [],
    "clientReferenceIntentId": "123456789",
    "paymentCreationErrors": [],
    "disbursementCreationErrors": [],
    "intentStatus": "CREATED"
}

{
    "intentId": "232510340021612544",
    "payments": [
        {
            "id": "232510340646563840",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authAmount": {
                "value": 100.05,
                "currency": "CNY"
            },
            "payer": {
                "countryIsoCode": "CNY"
            },
            "paymentInstrument": {
                "id": "PI204264628196626432",
                "paymentMethodId": "PM199507277233246209",
                "paymentMethodName": "UnionPay",
                "storedDetails": {
                    "returnUrl": ""
                }
            },
            "status": "ACCEPTED",
            "additionalData": {
                "qrBase64": "qrBase64",
                "url": "url"
            }
        }
    ],
    "disbursements": [],
    "clientReferenceIntentId": "123456789",
    "paymentCreationErrors": [],
    "disbursementCreationErrors": [],
    "intentStatus": "CREATED"
}

Section “QR Payment”

[2.7] Receive the webhook with the transaction status

🔗
More about Payment Callbacks on the dedicated page

After the transaction was processed and reached its final status (CAPTURED or DECLINED)
The Platform will notify you about the latest status change via the callback

SIMPLE WEBHOOK WITH TRANSACTION STATUS

    {  
      "status": "AUTHORIZED",
      "errorCode": "CODE_PT0000",
      "errorMessage": "string"
    }

Test Data

Our system allows emulating different test cases in the sandbox environment. To simulate specific scenarios and receive different results, use the intent.description parameter.

Alipay, WeChat, UnionPay Payment Testingflow

High-resolution image is available on the link: AliPay_WeChat_UnionPay_TestingFlow.jpg

Case	intent.description	final paymentStatus
Successful payment	--	CAPTURED
Payment Declined	DeclinedPayment	DECLINED
Failure	LinkCreationError	ERROR

Case "Successful payment"

Steps:

The client creates an intent via POST /processing/api/v1/intents.
A synchronous response is returned with paymentStatus = AUTHORIZATION_REQUESTED.
The client follows the link from payments. additionalData. url.
A callback is received with paymentStatus = CAPTURED.

Case "Payment Declined"

Steps:

The client creates an intent viaPOST /processing/api/v1/intents using the intent.description parameter with the value "DeclinedPayment".
A synchronous response is returned with paymentStatus = AUTHORIZATION_REQUESTED.
The client follows the link from payments. additionalData. url.
A callback is received with paymentStatus = DECLINED.

Case "Failure"

Steps:

The client creates an intent viaPOST /processing/api/v1/intents using the intent.description parameter with the value "LinkCreationError".
A synchronous response is returned with paymentStatus = ERROR.