📘
"paymentMethodName": "AliPay" OR "WeChatPay" OR "UnionPay"

Payment Method Features

Feature	AliPay	WeChatPay	UnionPay
Country	China	China	China
"paymentMethodName" in API	AliPay	WeChatPay	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	No	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

AliPay, WeChatPay, 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", "osType" = "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"}`
WeChatPay Web	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" : "WeChatPay"` `"incomingDetails": {"terminalType" = "WEB", "clientIp"=""}`
WeChatPay Wap	On the mobile browser, a shopper selects WeChatPay as a payment method on Merchant checkout, and as redirected from the browser into the WeChatPay app to complete the payment before being redirected back to the Merchant browser.	`"paymentMethodName" : "WeChatPay"` `"incomingDetails": {"terminalType" = "WAP", "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.

Intent Creation — Request / Response

📓
Request specifics

Endpoint: POST /processing/api/v1/intents

Purpose: Creates an Intent and a Payment for the selected payment method (AliPay / WeChatPay / UnionPay).

Structure: A unified request structure is used for all methods — only incomingDetails differs per method and scenario (see the Difference table above).

For these methods:

paymentMethodName must be AliPay, WeChatPay, or UnionPay

authCurrencyCode is always CNY

incomingDetails.returnUrl is required for all methods; terminalType, osType, and clientIp are conditional (see the field tables below)

Intent Request: Example

{
    "clientReferenceId": "1234",
    "payments": [
        {
            "paymentInstrument": {
                "paymentMethodName": "AliPay",
                "incomingDetails": {
                    "returnUrl": "http://example.com/",
                    "terminalType": "APP",
                    "osType": "IOS"
                }
            },
            "description": "Purchase description",
            "webhookUrl": "webhookUrl",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authCurrencyCode": "CNY"
        }
    ]
}

{
    "clientReferenceId": "1234",
    "payments": [
        {
            "paymentInstrument": {
                "paymentMethodName": "AliPay",
                "incomingDetails": {
                    "returnUrl": "http://example.com/",
                    "terminalType": "WEB"
                }
            },
            "description": "Purchase description",
            "webhookUrl": "webhookUrl",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authCurrencyCode": "CNY"
        }
    ]
}

{
    "clientReferenceId": "1234",
    "payments": [
        {
            "paymentInstrument": {
                "paymentMethodName": "WeChatPay",
                "incomingDetails": {
                    "returnUrl": "http://example.com/",
                    "terminalType": "WEB",
                    "clientIp": "clientIp"
                }
            },
            "description": "Purchase description",
            "webhookUrl": "webhookUrl",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authCurrencyCode": "CNY"
        }
    ]
}

{
    "clientReferenceId": "1234",
    "payments": [
        {
            "paymentInstrument": {
                "paymentMethodName": "WeChatPay",
                "incomingDetails": {
                    "returnUrl": "http://example.com/",
                    "terminalType": "WAP",
                    "clientIp": "clientIp"
                }
            },
            "description": "Purchase description",
            "webhookUrl": "webhookUrl",
            "submittedAmount": {
                "value": 100.05,
                "currency": "CNY"
            },
            "authCurrencyCode": "CNY"
        }
    ]
}

{
    "clientReferenceId": "1234",
    "payments": [
        {
            "paymentInstrument": {
                "paymentMethodName": "UnionPay",
                "incomingDetails": {
                    "returnUrl": "http://example.com/"
                }
            },
            "description": "Purchase description",
            "webhookUrl": "webhookUrl",
            "submittedAmount": {
                "value": 100.05,
                "currency": "USD"
            },
            "authCurrencyCode": "CNY"
        }
    ]
}

Intent Request: Fields Description

Top-Level Request Parameters

Parameter	Type	Required	Description
`clientReferenceId`	String	`Required`	The client/merchant intent reference (aka Transaction Reference).
`payments`	Array of Objects	`Required`	List of payment objects to be created within the `Intent`.

payment

Parameter	Type	Required	Description
`paymentInstrument`	Object	`Required`	Payment method and instrument details used to process the payment.
`submittedAmount`	Object	`Required`	Amount and currency submitted for the payment.
`authCurrencyCode`	String	`Required`	Authorisation currency in which the transaction is processed. Always `CNY` for these methods.
`description`	String	`Required`	Payment description (arbitrary string).
`webhookUrl`	String	`Optional`	URL to which payment status change webhooks will be sent.

paymentInstrument

Parameter	Type	Required	Description
`paymentMethodName`	String	`Required`	Payment method name. One of `AliPay`, `WeChatPay`, `UnionPay`.
`incomingDetails`	Object	`Required`	Method-specific data required to initiate the payment.

incomingDetails

Parameter	Type	Required	Methods	Description
`returnUrl`	String	`Required`	AliPay, WeChatPay, UnionPay	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`	String	`Conditional`	AliPay, WeChatPay	Depends on the payment method and scenario. AliPay: `APP` / `WEB`. WeChatPay: `WEB` / `WAP`.
`osType`	String	`Conditional`	AliPay	Required if `terminalType = APP`. Values: `IOS` / `ANDROID`.
`clientIp`	String	`Conditional`	WeChatPay	Required for WeChatPay.

submittedAmount

Parameter	Type	Required	Description
`value`	Number	`Required`	Transaction amount.
`currency`	String	`Required`	Original currency of the transaction. May differ from the auth currency; converted into `CNY` during processing.

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

{
    "transactionType": "PAYMENT",
    "transactionId": "111122223333444455",
    "status": "ACCEPTED"
}

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, WeChatPay, UnionPay Payment Test flow

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

Case Description

Case Name	intent.description	Scenario
Successful payment	-- (no keywords required)	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.details.url`. A callback is received with `paymentStatus = CAPTURED`.
Payment Declined	"DeclinedPayment" keyword must be added into the intent's description	The client creates an intent via`POST /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.details.url`. A callback is received with `paymentStatus = DECLINED`.
Link Creation Failure	"LinkCreationError" keyword must be added into the intent's description	The client creates an intent via`POST /processing/api/v1/intents` using the `intent.description` parameter with the value `"LinkCreationError"`. A synchronous response is returned with `paymentStatus = ERROR`.