Last updated: 01 October 2025 | Change log
WeChat Pay, officially referred to as Weixin Pay in China, is a mobile payment and digital wallet service.
Note
Make yourself familiar with our API Principles to ensure a resilient integration.
Product Overview
WeChat Pay is a digital wallet allowing your customers to make online or mobile wallet payments. It is considered a vital payment method if you are operating in China.
| Payment type | Recurring | Reversals | Partial Reversals | Disputes | Auth and Settlement (Sale) |
|---|---|---|---|---|---|
| Digital wallet | ❌ | ✅ | ✅ | ❌ | ✅ |
- Maximum Transaction Value: 50.000 CNY
- Maximum Transaction per consumer wallet per day: 100.000 CNY
Acceptance currencies
| Currency | Currency codes |
|---|---|
| Australian Dollar | AUD |
| Canadian Dollar | CAD |
| Chinese Yuan | CNY |
| Euro | EUR |
| Hong Kong Dollar | HKD |
| Japanese Yen | JPY |
| New Zeland Dollar | NZD |
| Pound Sterling | GBP |
| US Dollar | USD |
| Singapore Dollar | SGD |
Setting your headers is an important part of an API request. The headers represent the meta-data associated with your API request.
Authorization: {your_credentials}
Content-Type: application/json
WP-Api-Version: 2023-06-01| Header | Description |
|---|---|
Authorization | We use the Authorization header to identify and authenticate you within Access Worldpay. You must use the Authorization header for any request you send to our APM API. |
Content-Type | We require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a POST or a PUT. |
WP-Api-Version | We use the WP-Api-Version header to identify which version of our APM API you are using. You must use the WP-Api-Version header for any request you send to our API. |
If you're using both the Content-Type and WP-Api-Version headers, they must match.
Note
Replace {your_credentials} with your base64-encoded Basic Auth username and password. To get your Access Worldpay credentials contact your Implementation Manager.
POST https://try.access.worldpay.com/apmPayments
{
"transactionReference": "Memory265-13/08/1876",
"merchant":
{
"entity": "default"
},
"instruction":
{
"narrative":
{
"line1": "Mind Palace Ltd"
},
"value":
{
"amount": 500,
"currency": "CNY"
},
"paymentInstrument":
{
"type": "wechatpay",
"language": "zh",
"country": "CN",
"successURL": "https://example.com/success",
"pendingURL": "https://example.com/pending",
"failureURL": "https://example.com/failure",
"cancelURL": "https://example.com/cancel",
"transactionTimeOut": 10
}
}
}| Parameter | Required? | Description | Data type | Length |
|---|---|---|---|---|
merchant | ✅ | An object that contains information about the merchant. | Object | N/A |
merchant.entity | ✅ | Direct your payment to assist with billing, reporting and reconciliation. This is mandatory for Authentication and Queries. Contact your Implementation Manager for more details. | String | Must be between 1 and 32 characters. |
transactionReference | ✅ | A unique reference generated by you that is used to identify a payment throughout its lifecycle. See transaction reference format. | String | Must be between 1 to 64 characters. |
instruction | ✅ | An object that contains all the information related to the payment. | Object | N/A |
instruction.narrative | ✅ | An object that helps your customers better identify you on their statement. | Object | See our formatting rules |
instruction.narrative.line1 | ✅ | The first line of the narrative which appears on your customer's statement (If a character is not supported it is replaced with a space.). See narrative line1 format for more details. | Object | 24 |
instruction.value | ✅ | An object that contains information about the payment transaction. | Object | N/A |
instruction.value.amount | ✅ | The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2,50. You can find the relevant exponent in our currency table. | Integer | N/A |
instruction.value.currency | ✅ | The payment currency. Refer to the individual APM page for supported currencies. | Integer | 3 |
instruction.paymentInstrument | ✅ | An object that contains information about the payment method. | Object | N/A |
instruction.paymentInstrument.type | ✅ | An object that contains the payment type and details. It defines which alternative payment method you wish to use. Value is wechatpay. | Object | N/A |
instruction.paymentInstrument.language | ❌ | An object that contains the language of your customer. Follows ISO 639-1 standard. | String | 2 |
paymentInstrument.country | ❌ | The country of your customer. Follows alpha 2 ISO 3166-1 standard. | Object | 2 |
instruction.paymentInstrument.cancelURL | ❌ | When your customer cancels a transaction, we redirect your customer to that cancel URL. | String | N/A |
instruction.paymentInstrument.pendingURL | ❌ | When we receive the payment result for a pending payment transaction, we redirect your customer to that pending URL. | String | N/A |
instruction.paymentInstrument.successURL | ❌ | When we receive the payment result for a successful payment, we redirect your customer to that success URL. | String | N/A |
instruction.paymentInstrument.transactionTimeOut | ❌ | The time your customer has to complete the payment before timing out, in minutes. | Integer | 3 |
Recommendation
We suggest you provide the cancelURL, pendingURL and successURL attribute to redirect your customer to, once you have received the payment result.
- an HTTP code
201 - an
idwhich is unique to the payment - we recommend storing the "id" as this can be used to manage the payment later - a
urlto redirect your customer to the APM provider to complete the payment - a link to query the payment status
{
"paymentId": "nFxASqw-LV9HE_rr1mMONJmqBDeXmnv5dzt9IxAXgXbfpu0O_8mOnTpFSIM9gnTSygCKQgvlwQdUbu5rExIpJA_5Uq2LEGXXAanycRpxfDPNA-E70zIWdnaMb2gJhC8AIhbOkM6xDiVNu90YCXo2snTzi_k1sEOQnKIAJNTW3Qc",
"lastEvent": "pending",
"_links": {
"self": {
"href": "https://access.worldpay.com/apmPayments/nFxASqw-LV9HE_rr1mMONJmqBDeXmnv5dzt9IxAXgXbfpu0O_8mOnTpFSIM9gnTSygCKQgvlwQdUbu5rExIpJA_5Uq2LEGXXAanycRpxfDPNA-E70zIWdnaMb2gJhC8AIhbOkM6xDiVNu90YCXo2snTzi_k1sEOQnKIAJNTW3Qc"
}
},
"_actions": {},
"url": "https://payments.worldpay.com/app/hpp/integration/wpg/corporate?OrderKey="
}Note
In case of an error, you can get further information in our error reference.
Next Steps