WeChat Pay

Last updated: December 11, 2024

WeChat Pay enables customers to perform secure online payments.

We offer the following WeChat Pay payment types:

To use in-app, mini program, or official account payments, you must register with WeChat Pay.

Once you've registered and the entity is authenticated, you can view your appid on the WeChat Open Platform. If you've registered for multiple WeChat payment methods, you'll be provided with a unique appid for each one.

Information

To enable WeChat Pay payments on your account, contact your Account Manager or [email protected].

Model	Collecting/Gateway
Payment flow	Redirect
Payment method type	Wallet
Auto-capture payment
Authorization
Capture
Refund
Partial refund
Chargeback
Recurring payment

Accept WeChat payments by presenting a QR code to your customers, which they can scan with the WeChat mobile app.

After the customer completes or fails the payment, they are redirected back to your payment page. You'll also receive an asynchronous payment result which you can display to the customer.

Use the details below to set up your request. To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments


1{
2  "amount": 50,
3  "currency": "HKD",
4  "source": {
5    "type": "wechatpay",
6    "billing_address": {
7      "address_line1": "123 Example St.",
8      "address_line2": "Apt. 456",
9      "city": "Wan Chai",
10      "state": "",
11      "zip": "42345",
12      "country": "HK"
13    }
14  },
15  "failure_url": "https://example.com/payments/failure",
16  "success_url": "https://example.com/payments/success",
17  "reference": "ORD-5023-4E89",
18  "processing_channel_id": "{{processing-channel-id}}",
19  "customer": {
20    "name": "John Smith",
21    "email": "[email protected]",
22    "phone": {
23      "country_code": "+852",
24      "number": "564649440"
25    }
26  },
27  "shipping": {
28    "address": {
29      "address_line1": "123 Example St.",
30      "address_line2": "Apt. 456",
31      "city": "Wan Chai",
32      "state": "",
33      "zip": "42345",
34      "country": "HK"
35    }
36  },
37  "capture_on": "2022-03-15T10:11:12Z",
38  "capture": true,
39  "processing": {
40    "tax_amount": 10,
41    "shipping_amount": 10,
42    "product_type": "QR Code"
43  },
44  "items": [
45    {
46      "name": "Item name",
47      "quantity": 1,
48      "unit_price": 30,
49      "total_amount": 30,
50      "tax_amount": 10,
51      "discount_amount": 10,
52      "reference": "some description about item",
53      "image_url": "https://some_s3bucket.com",
54      "url": "https://some.website.com/item",
55      "wxpay_goods_id": "1001"
56    }
57  ],
58  "payment_ip": "90.197.169.245"
59}

If you receive a 202 Accepted response with a status field set to Pending, your request was successful.


1{
2  "id": "pay_gdbok753fk3ebk4dpq7xqq72te",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_ujs5uvwcshhujllodxegkknwou",
7    "email": "[email protected]",
8    "name": "John Smith",
9    "phone": {
10      "number": "123456789",
11      "country_code": "+852"
12    }
13  },
14  "processing": {
15    "partner_payment_id": "fedc4728c87d0709fceaf1c8b6945cce"
16  },
17  "_links": {
18    "self": {
19      "href": "https://api.sandbox.checkout.com/payments/pay_gdbok753fk3ebk4dpq7xqq72te"
20    },
21    "redirect": {
22      "href": "weixin://wxpay/bizpayurl?pr=MQ4aYOXzz"
23    }
24  }
25}

Take the URL from the _links.redirect.href field and convert it into a QR code using a third-party QR code generator tool.

Display the QR code to the customer, so that they can scan it with the WeChat Pay mobile app to complete the transaction.

Integrate the WeChat SDK into your Android or iOS app to use in-app payments, which allow you to offer your goods or services through your mobile app.

When a customer selects the WeChat Pay payment method from within your app, they are redirected to the WeChat app to verify the payment. Once the payment is completed, they are redirected back to your app, where you can display the payment result.

Contact your Account Manager for more information.

Use the details below to set up your request. To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments


1{
2  "amount": 50,
3  "currency": "HKD",
4  "source": {
5    "type": "wechatpay",
6    "billing_address": {
7      "address_line1": "123 Example St.",
8      "address_line2": "Apt. 456",
9      "city": "Wan Chai",
10      "state": "",
11      "zip": "42345",
12      "country": "HK"
13    }
14  },
15  "failure_url": "https://example.com/payments/failure",
16  "success_url": "https://example.com/payments/success",
17  "reference": "ORD-5023-4E89",
18  "processing_channel_id": "{{processing-channel-id}}",
19  "customer": {
20    "name": "John Smith",
21    "email": "[email protected]",
22    "phone": {
23      "country_code": "+852",
24      "number": "123456789"
25    }
26  },
27  "shipping": {
28    "address": {
29      "address_line1": "123 Example St.",
30      "address_line2": "Apt. 456",
31      "city": "Wan Chai",
32      "state": "",
33      "zip": "42345",
34      "country": "HK"
35    }
36  },
37  "capture_on": "2019-09-10T10:11:12Z",
38  "capture": true,
39  "processing": {
40    "tax_amount": 10,
41    "shipping_amount": 10,
42    "product_type": "In-App",
43    "original_order_amount": 10
44  },
45  "items": [
46    {
47      "name": "Item name",
48      "quantity": 1,
49      "unit_price": 30,
50      "total_amount": 30,
51      "tax_amount": 10,
52      "discount_amount": 10,
53      "reference": "some description about item",
54      "image_url": "https://some_s3bucket.com",
55      "url": "https://some.website.com/item",
56      "wxpay_goods_id": "1001"
57    }
58  ],
59  "payment_ip": "90.197.169.245"
60}

If you receive a 202 Accepted response with a status field set to Pending, your request was successful.


1{
2  "id": "pay_txjup4rkax2utcifmwzfjgzsia",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_ujs5uvwcshhujllodxegkknwou",
7    "email": "[email protected]",
8    "name": "John Smith",
9    "phone": {
10      "number": "123456789",
11      "country_code": "+852"
12    }
13  },
14  "processing": {
15    "partner_payment_id": "7385e8fb9a5bac0d42ff3db17e3efea9",
16    "continuation_payload": "{\"prepay_id\":\"wx02161421698644ab471821297252eb0000\",\"partner_id\":\"1900012731\",\"timestamp\":1651479262,\"app_id\":\"sub_application_id\",\"nonce\":\"476d17edadf44915ad533107bd3c71c2\",\"sign\":\"QM1CCVAkexZLq00Uz/IxgbqC2ke7Xl9xUayutALc1EebLT1cI85H0biNNjhzQrzFdJ0YCq8KR2Hc9bD01vxRsn18fHzE5bhvn2qlUSOeY7hATfaLYS7+f+gKVj+0iIuUp3qamquErrKYl1g1Vhvlwn1U8TrcjhU0w666YYJuwIP9qPNy6F8wj3ORWM1uYmB9D4v09sTnmZfBPFwuGJzj2PTBGyvoKLu+V1T1HzlC2rwhpDmrSCq0rcFL2smztWGVktpZ2NoggEAVWLjHWsvS8OmzgeosM3ltoCeWjlp1SusmXtlMtUJWyjiVQYHnjb/a42NYk/qynZ/w+BAqLTlDKA==\",\"pkg\":\"Sign=WXPay\"}"
17  },
18  "_links": {
19    "self": {
20      "href": "https://api.sandbox.checkout.com/payments/pay_txjup4rkax2utcifmwzfjgzsia"
21    }
22  }
23}

After you receive a response from Checkout.com, you need to use the WeChat SDK to make a call with a specific set of parameters, depending on the region in which you are operating:

Region where you are operating	SDK documentation
Hong Kong, Japan, Macau	In-App Pay – Chapter 6.4
Others	In-App Pay - Chapter 6.3

A mini program is a program created from within the WeChat app, typically used to direct users to an online shop from an offline storefront.

When a customer opens your mini program and places an order, they are redirected to WeChat control to enter their payment password in order to complete the payment. Once the payment is completed, they are returned to your mini program.

Before requesting a payment using our Unified Payments API, request the open_id with your mini program.

To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments


1{
2  "amount": 50,
3  "currency": "HKD",
4  "source": {
5    "type": "wechatpay",
6    "billing_address": {
7      "address_line1": "123 Example St.",
8      "address_line2": "Apt. 456",
9      "city": "Wan Chai",
10      "state": "",
11      "zip": "42345",
12      "country": "HK"
13    }
14  },
15  "failure_url": "https://example.com/payments/failure",
16  "success_url": "https://example.com/payments/success",
17  "reference": "ORD-5023-4E89",
18  "processing_channel_id": "{{processing-channel-id}}",
19  "customer": {
20    "name": "John Smith",
21    "email": "[email protected]",
22    "phone": {
23      "country_code": "+852",
24      "number": "123456789"
25    }
26  },
27  "shipping": {
28    "address": {
29      "address_line1": "123 Example St.",
30      "address_line2": "Apt. 456",
31      "city": "Wan Chai",
32      "state": "",
33      "zip": "42345",
34      "country": "HK"
35    }
36  },
37  "capture_on": "2019-09-10T10:11:12Z",
38  "capture": true,
39  "processing": {
40    "tax_amount": 10,
41    "shipping_amount": 10,
42    "product_type": "Mini Program",
43    "original_order_amount": 10,
44    "open_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
45  },
46  "items": [
47    {
48      "name": "Item name",
49      "quantity": 1,
50      "unit_price": 30,
51      "total_amount": 30,
52      "tax_amount": 10,
53      "discount_amount": 10,
54      "reference": "some description about item",
55      "image_url": "https://some_s3bucket.com",
56      "url": "https://some.website.com/item",
57      "wxpay_goods_id": "1001"
58    }
59  ],
60  "payment_ip": "90.197.169.245"
61}

If you receive a 202 Accepted response with a status field set to Pending, your request was successful.


1{
2  "id": "pay_i3pquwatsxuufih4ceqtany7ga",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_ujs5uvwcshhujllodxegkknwou",
7    "email": "[email protected]",
8    "name": "John Smith",
9    "phone": {
10      "number": "123456789",
11      "country_code": "+852"
12    }
13  },
14  "processing": {
15    "partner_payment_id": "19646ff4b9ef3bdd833305319edf9346",
16    "continuation_payload": "{\"prepay_id\":\"wx02161421698644ab471821297252eb0000\",\"timestamp\":1651479262,\"app_id\":\"sub_application_id\",\"nonce\":\"476d17edadf44915ad533107bd3c71c2\",\"sign\":\"QM1CCVAkexZLq00Uz/IxgbqC2ke7Xl9xUayutALc1EebLT1cI85H0biNNjhzQrzFdJ0YCq8KR2Hc9bD01vxRsn18fHzE5bhvn2qlUSOeY7hATfaLYS7+f+gKVj+0iIuUp3qamquErrKYl1g1Vhvlwn1U8TrcjhU0w666YYJuwIP9qPNy6F8wj3ORWM1uYmB9D4v09sTnmZfBPFwuGJzj2PTBGyvoKLu+V1T1HzlC2rwhpDmrSCq0rcFL2smztWGVktpZ2NoggEAVWLjHWsvS8OmzgeosM3ltoCeWjlp1SusmXtlMtUJWyjiVQYHnjb/a42NYk/qynZ/w+BAqLTlDKA==\",\"pkg\":\"prepay_id=wx02161421698644ab471821297252eb0000\"}"
17  },
18  "_links": {
19    "self": {
20      "href": "https://api.sandbox.checkout.com/payments/pay_i3pquwatsxuufih4ceqtany7ga"
21    }
22  }
23}

After you receive a response from Checkout.com, you need to use the WeChat SDK to make a call with a specific set of parameters, depending on the region in which you are operating:

Region where you are operating	SDK documentation
Hong Kong, Japan, Macau	Mini Program Pay - Chapter 7
Others	In-App Pay - Chapter 6

An official account is a tool that helps to manage and understand your users. Merchants can regularly promote their brands and services through their official accounts to encourage users to spend money in their physical or online stores.

An official account payment refers to a customer opening your website in the WeChat web view and loading the WeChat payment plugin.

When a customer has accessed your website and added goods to their cart, they are redirected to WeChat control to enter their payment details. Once the details have been verified and the payment has been authorized, they are redirected back to your website, where you can display a purchase confirmation message.

Before requesting a payment using our Unified Payments API, request the open_id.

To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments


1{
2  "amount": 50,
3  "currency": "HKD",
4  "source": {
5    "type": "wechatpay",
6    "billing_address": {
7      "address_line1": "150 Kennedy Road",
8      "address_line2": "Acacia Building",
9      "city": "Wan Chai",
10      "state": "",
11      "zip": "42345",
12      "country": "HK"
13    }
14  },
15  "failure_url": "https://example.com/payments/failure",
16  "success_url": "https://example.com/payments/success",
17  "reference": "ORD-5023-4E89",
18  "processing_channel_id": "{{processing-channel-id}}",
19  "customer": {
20    "name": "John Smith",
21    "email": "[email protected]",
22    "phone": {
23      "country_code": "+852",
24      "number": "564649440"
25    }
26  },
27  "shipping": {
28    "address": {
29      "address_line1": "150 Kennedy Road",
30      "address_line2": "Acacia Building",
31      "city": "Wan Chai",
32      "state": "",
33      "zip": "42345",
34      "country": "HK"
35    }
36  },
37  "capture_on": "2019-09-10T10:11:12Z",
38  "capture": true,
39  "processing": {
40    "tax_amount": 10,
41    "shipping_amount": 10,
42    "product_type": "Official Account",
43    "original_order_amount": 10,
44    "open_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
45  },
46  "items": [
47    {
48      "name": "Item name",
49      "quantity": 1,
50      "unit_price": 30,
51      "total_amount": 30,
52      "tax_amount": 10,
53      "discount_amount": 10,
54      "reference": "some description about item",
55      "image_url": "https://some_s3bucket.com",
56      "url": "https://some.website.com/item",
57      "wxpay_goods_id": "1001"
58    }
59  ],
60  "payment_ip": "90.197.169.245"
61}

If you receive a 202 Accepted response with a status field set to Pending, your request was successful.


1{
2  "id": "pay_qlccwywng5zu7mw2pwumnnjdw4",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_ujs5uvwcshhujllodxegkknwou",
7    "email": "[email protected]",
8    "name": "John Smith",
9    "phone": {
10      "number": "564649440",
11      "country_code": "+852"
12    }
13  },
14  "processing": {
15    "partner_payment_id": "e1e1edc91117561f3063e9c5a305f914",
16    "continuation_payload": "{\"prepay_id\":\"wx02161421698644ab471821297252eb0000\",\"timestamp\":1651479262,\"app_id\":\"sub_application_id\",\"nonce\":\"476d17edadf44915ad533107bd3c71c2\",\"sign\":\"QM1CCVAkexZLq00Uz/IxgbqC2ke7Xl9xUayutALc1EebLT1cI85H0biNNjhzQrzFdJ0YCq8KR2Hc9bD01vxRsn18fHzE5bhvn2qlUSOeY7hATfaLYS7+f+gKVj+0iIuUp3qamquErrKYl1g1Vhvlwn1U8TrcjhU0w666YYJuwIP9qPNy6F8wj3ORWM1uYmB9D4v09sTnmZfBPFwuGJzj2PTBGyvoKLu+V1T1HzlC2rwhpDmrSCq0rcFL2smztWGVktpZ2NoggEAVWLjHWsvS8OmzgeosM3ltoCeWjlp1SusmXtlMtUJWyjiVQYHnjb/a42NYk/qynZ/w+BAqLTlDKA==\",\"pkg\":\"prepay_id=wx02161421698644ab471821297252eb0000\"}"
17  },
18  "_links": {
19    "self": {
20      "href": "https://api.sandbox.checkout.com/payments/pay_qlccwywng5zu7mw2pwumnnjdw4"
21    }
22  }
23}

After you receive a response from Checkout.com, you need to use the WeChat SDK to make a call with a specific set of parameters, depending on the region in which you are operating:

Region where you are operating	SDK documentation
Hong Kong, Japan, Macau	Official Payment - Chapter 5.5
Others	Official Payment - Chapter 5.3

You can retrieve details about an existing WeChat Pay payment by using the payment id found in the payment response. To get a detailed view of all required and optional fields, see our API reference.

get

https://api.checkout.com/payments/{id}


1{
2  "id": "pay_ri6ok2tsm3yujbs3kjkg44hf34",
3  "requested_on": "2022-03-21T11:21:39.0426045Z",
4  "source": {
5    "type": "wechatpay"
6  },
7  "items": [
8    {
9      "name": "Item name",
10      "quantity": 1,
11      "unit_price": 30,
12      "reference": "some description about item",
13      "image_url": "https://some_s3bucket.com",
14      "url": "https://some.website.com/item",
15      "total_amount": 30,
16      "tax_amount": 10,
17      "discount_amount": 10,
18      "wxpay_goods_id": "1001"
19    }
20  ],
21  "amount": 50,
22  "currency": "HKD",
23  "payment_type": "Regular",
24  "reference": "ORD-5023-4E89",
25  "status": "Pending",
26  "customer": {
27    "id": "cus_ujs5uvwcshhujllodxegkknwou",
28    "email": "[email protected]",
29    "name": "John Smith",
30    "phone": {
31      "country_code": "+852",
32      "number": "123456789"
33    }
34  },
35  "shipping": {
36    "address": {
37      "address_line1": "123 Example St.",
38      "address_line2": "Apt. 456",
39      "city": "Wan Chai",
40      "state": "",
41      "zip": "42345",
42      "country": "HK"
43    }
44  },
45  "payment_ip": "90.197.169.245",
46  "processing": {
47    "partner_payment_id": "5167891a61704147404f29d6371fd702"
48  },
49  "_links": {
50    "redirect": {
51      "href": "weixin://wxpay/bizpayurl?pr=QWwHcAdzz"
52    },
53    "self": {
54      "href": "https://api.sandbox.checkout.com/payments/pay_ri6ok2tsm3yujbs3kjkg44hf34"
55    },
56    "actions": {
57      "href": "https://api.sandbox.checkout.com/payments/pay_ri6ok2tsm3yujbs3kjkg44hf34/actions"
58    }
59  }
60}

WeChat Pay supports full, partial and multiple partial refunds for all payment types.

You can process a refund through the Dashboard or using the Refund API. However, there is no chargeback or dispute mechanism available for WeChat Pay.

To get a detailed view of all required and optional fields, see our API reference.

post

https://api.checkout.com/payments/{id}/refunds


1{
2  "amount": 100
3}


1{
2  "action_id": "act_jf7fv3vgiu7ezjfgzvvsqobxru",
3  "_links": {
4    "payment": {
5      "href": "https://api.sandbox.checkout.com/payments/pay_fsud3hyoqkxencjvb5cfv6yqoe"
6    }
7  }
8}

You may receive the following webhooks when using WeChat Pay:

Webhook	Description
`payment_pending`	Sent when a merchant initiates a payment request.
`payment_capture_pending`	Sent when a payment request has been successfully initiated and the payment capture is pending.
`payment_captured`	Sent when the payment has been successfully captured.
`payment_declined`	Sent when a payment request has been rejected.
`payment_expired`	Sent when the payment has expired. WeChat payments expire after 10 minutes.
`payment_refund_pending`	Sent when the refund of the payment has been (fully or partially) accepted.
`payment_refunded`	Sent when the payment has been (fully or partially) refunded.
`payment_refund_declined`	Sent when a refund has been declined.

You can refer to our webhook event types for a full list of our webhook notifications.

Before you begin testing, you must have a WeChat Pay account and app.

You'll also need to contact your Account Manager to enable WeChat Pay payments in your sandbox environment. When doing so, please specify your region, processing currency, and settlement currency.

Create a WeChat Pay payment transaction based on a payment type as described in this documentation.
Check the transaction response in the sandbox environment.
Depending on the payment type used, either take the QR code data from _links.redirect.href and convert it into a QR code or invoke WeChat SDK with the required parameters.
Complete the payment transaction and check the result status.

Information

When testing refunds in the Sandbox environment, you must refund the test transaction within one hour of performing it.

WeChat requires that all merchants who process payments with them display the WeChat Pay logo on their website. See the WeChat regulations documentation for more information.

Merchants must also mention in their privacy policy that all Tenpay Transactions are subject to the Tenpay Privacy Policy, in addition to any other applicable privacy policies.

WeChat Pay

Information

QR code payment

Request a payment

Request example

Response example

Create and display the QR code

In-app payment

Request a payment

Request example

Response example

Mini program payment

Request a payment

Request example

Response example

Official account payment

Request a payment

Request example

Response example

Get details about a payment

Response example

Refunds and chargebacks

Request example

Response example

Supported webhooks

Testing WeChat Pay

Information

WeChat Pay requirements