WeChat Pay
Last updated: August 21, 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 support@checkout.com.
Model | Collecting/Gateway |
---|---|
Payment flow | Redirect |
Payment method type | Wallet |
One-step 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": "john.smith@example.com",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": "john.smith@example.com",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": "john.smith@example.com",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": 1044},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": "john.smith@example.com",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 | |
Others |
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": "john.smith@example.com",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": "john.smith@example.com",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 | |
Others |
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": "john.smith@example.com",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": "john.smith@example.com",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 | |
Others |
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": "john.smith@example.com",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": 1003}
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 |
---|---|
| Sent when a merchant initiates a payment request. |
| Sent when a payment request has been successfully initiated and the payment capture is pending. |
| Sent when the payment has been successfully captured. |
| Sent when a payment request has been rejected. |
| Sent when the payment has expired. WeChat payments expire after 10 minutes. |
| Sent when the refund of the payment has been (fully or partially) accepted. |
| Sent when the payment has been (fully or partially) refunded. |
| 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.