# WeChat Pay for Unified Payments API

We offer the following WeChat Pay payment types:

- [QR code](#QR_code_payment)
- [In-app](#In-app_payment)
- [Mini program](#Mini_program_payment)
- [Official account](#Official_account_payment)

To use in-app, mini program, or official account payments, you must [register with WeChat Pay](https://pay.weixin.qq.com/index.php/public/wechatpay_en/application_direct_merchants).

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.

---

## QR code payment

Accept WeChat payments by presenting a [QR code](https://pay.weixin.qq.com/index.php/public/wechatpay_en/product_intro?name=qrcode) 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.

### Request a payment

Use the following details to set up your request. To get a detailed view of all required and optional fields, see our [API reference](https://api-reference.checkout.com).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "amount": 50,
  "currency": "HKD",
  "source": {
    "type": "wechatpay",
    "billing_address": {
      "address_line1": "123 Example St.",
      "address_line2": "Apt. 456",
      "city": "Wan Chai",
      "state": "",
      "zip": "42345",
      "country": "HK"
    }
  },
  "failure_url": "https://example.com/payments/failure",
  "success_url": "https://example.com/payments/success",
  "reference": "ORD-5023-4E89",
  "processing_channel_id": "{{processing-channel-id}}",
  "customer": {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "phone": {
      "country_code": "+852",
      "number": "564649440"
    }
  },
  "shipping": {
    "address": {
      "address_line1": "123 Example St.",
      "address_line2": "Apt. 456",
      "city": "Wan Chai",
      "state": "",
      "zip": "42345",
      "country": "HK"
    }
  },
  "capture_on": "2022-03-15T10:11:12Z",
  "capture": true,
  "processing": {
    "tax_amount": 10,
    "shipping_amount": 10,
    "product_type": "QR Code"
  },
  "items": [
    {
      "name": "Item name",
      "quantity": 1,
      "unit_price": 30,
      "total_amount": 30,
      "tax_amount": 10,
      "discount_amount": 10,
      "reference": "ORDER_01234",
      "image_url": "https://some_s3bucket.com",
      "url": "https://some.website.com/item",
      "wxpay_goods_id": "1001"
    }
  ],
  "payment_ip": "90.197.169.245"
}
```

#### Response example

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

```json
{
  "id": "pay_gdbok753fk3ebk4dpq7xqq72te",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "john.smith@example.com",
    "name": "John Smith",
    "phone": {
      "number": "123456789",
      "country_code": "+852"
    }
  },
  "processing": {
    "partner_payment_id": "fedc4728c87d0709fceaf1c8b6945cce"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_gdbok753fk3ebk4dpq7xqq72te"
    },
    "redirect": {
      "href": "weixin://wxpay/bizpayurl?pr=MQ4aYOXzz"
    }
  }
}
```

### Create and display the QR code

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.

---

## In-app payment

Integrate the WeChat SDK into your [Android](https://developers.weixin.qq.com/doc/oplatform/en/Mobile_App/Access_Guide/Android.html) or [iOS](https://developers.weixin.qq.com/doc/oplatform/en/Mobile_App/Access_Guide/iOS.html) app to use [in-app payments](https://pay.weixin.qq.com/index.php/public/wechatpay_en/product_intro?name=app), 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.

### Request a payment

Use the following details to set up your request. To get a detailed view of all required and optional fields, see our [API reference](https://api-reference.checkout.com).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "amount": 50,
  "currency": "HKD",
  "source": {
    "type": "wechatpay",
    "billing_address": {
      "address_line1": "123 Example St.",
      "address_line2": "Apt. 456",
      "city": "Wan Chai",
      "state": "",
      "zip": "42345",
      "country": "HK"
    }
  },
  "failure_url": "https://example.com/payments/failure",
  "success_url": "https://example.com/payments/success",
  "reference": "ORD-5023-4E89",
  "processing_channel_id": "{{processing-channel-id}}",
  "customer": {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "phone": {
      "country_code": "+852",
      "number": "123456789"
    }
  },
  "shipping": {
    "address": {
      "address_line1": "123 Example St.",
      "address_line2": "Apt. 456",
      "city": "Wan Chai",
      "state": "",
      "zip": "42345",
      "country": "HK"
    }
  },
  "capture_on": "2024-09-10T10:11:12Z",
  "capture": true,
  "processing": {
    "tax_amount": 10,
    "shipping_amount": 10,
    "product_type": "In-App",
    "original_order_amount": 10
  },
  "items": [
    {
      "name": "Item name",
      "quantity": 1,
      "unit_price": 30,
      "total_amount": 30,
      "tax_amount": 10,
      "discount_amount": 10,
      "reference": "ORDER_01234",
      "image_url": "https://some_s3bucket.com",
      "url": "https://some.website.com/item",
      "wxpay_goods_id": "1001"
    }
  ],
  "payment_ip": "90.197.169.245"
}
```

#### Response example

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

```json
{
  "id": "pay_txjup4rkax2utcifmwzfjgzsia",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "john.smith@example.com",
    "name": "John Smith",
    "phone": {
      "number": "123456789",
      "country_code": "+852"
    }
  },
  "processing": {
    "partner_payment_id": "7385e8fb9a5bac0d42ff3db17e3efea9",
    "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\"}"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_txjup4rkax2utcifmwzfjgzsia"
    }
  }
}
```

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](https://pay.weixin.qq.com/wiki/doc/api/wxpay/en/fusion_wallet/In-AppPay/chapter6_4.shtml) |
| Others | [In-App Pay - Chapter 6.3](https://pay.weixin.qq.com/wiki/doc/api/wxpay/en/pay/In-AppPay/chapter6_3.shtml) |

---

## Mini program payment

A [mini program](https://pay.weixin.qq.com/index.php/public/wechatpay_en/product_intro?name=miniapp) 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.

### Request a payment

Before requesting a payment using the Payments API, [request the `open_id` with your mini program](https://developers.weixin.qq.com/miniprogram/en/dev/api/open-api/login/wx.login.html).

To get a detailed view of all required and optional fields, see our [API reference](https://api-reference.checkout.com).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "amount": 50,
  "currency": "HKD",
  "source": {
    "type": "wechatpay",
    "billing_address": {
      "address_line1": "123 Example St.",
      "address_line2": "Apt. 456",
      "city": "Wan Chai",
      "state": "",
      "zip": "42345",
      "country": "HK"
    }
  },
  "failure_url": "https://example.com/payments/failure",
  "success_url": "https://example.com/payments/success",
  "reference": "ORD-5023-4E89",
  "processing_channel_id": "{{processing-channel-id}}",
  "customer": {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "phone": {
      "country_code": "+852",
      "number": "123456789"
    }
  },
  "shipping": {
    "address": {
      "address_line1": "123 Example St.",
      "address_line2": "Apt. 456",
      "city": "Wan Chai",
      "state": "",
      "zip": "42345",
      "country": "HK"
    }
  },
  "capture_on": "2024-09-10T10:11:12Z",
  "capture": true,
  "processing": {
    "tax_amount": 10,
    "shipping_amount": 10,
    "product_type": "Mini Program",
    "original_order_amount": 10,
    "open_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
  },
  "items": [
    {
      "name": "Item name",
      "quantity": 1,
      "unit_price": 30,
      "total_amount": 30,
      "tax_amount": 10,
      "discount_amount": 10,
      "reference": "ORDER_01234",
      "image_url": "https://some_s3bucket.com",
      "url": "https://some.website.com/item",
      "wxpay_goods_id": "1001"
    }
  ],
  "payment_ip": "90.197.169.245"
}
```

#### Response example

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

```json
{
  "id": "pay_i3pquwatsxuufih4ceqtany7ga",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "john.smith@example.com",
    "name": "John Smith",
    "phone": {
      "number": "123456789",
      "country_code": "+852"
    }
  },
  "processing": {
    "partner_payment_id": "19646ff4b9ef3bdd833305319edf9346",
    "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\"}"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_i3pquwatsxuufih4ceqtany7ga"
    }
  }
}
```

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](https://pay.weixin.qq.com/wiki/doc/api/wxpay/en/fusion_wallet/MiniProgramPay/chapter7_4.shtml) |
| Others | [In-App Pay - Chapter 6](https://pay.weixin.qq.com/wiki/doc/api/wxpay/en/pay/In-AppPay/chapter6_3.shtml) |

---

## Official account payment

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.

### Request a payment

Before requesting a payment using the Payments API, [request the `open_id`](https://developers.weixin.qq.com/doc/offiaccount/en/OA_Web_Apps/Wechat_webpage_authorization.html).

To get a detailed view of all required and optional fields, see our [API reference](https://api-reference.checkout.com).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "amount": 50,
  "currency": "HKD",
  "source": {
    "type": "wechatpay",
    "billing_address": {
      "address_line1": "150 Kennedy Road",
      "address_line2": "Acacia Building",
      "city": "Wan Chai",
      "state": "",
      "zip": "42345",
      "country": "HK"
    }
  },
  "failure_url": "https://example.com/payments/failure",
  "success_url": "https://example.com/payments/success",
  "reference": "ORD-5023-4E89",
  "processing_channel_id": "{{processing-channel-id}}",
  "customer": {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "phone": {
      "country_code": "+852",
      "number": "564649440"
    }
  },
  "shipping": {
    "address": {
      "address_line1": "150 Kennedy Road",
      "address_line2": "Acacia Building",
      "city": "Wan Chai",
      "state": "",
      "zip": "42345",
      "country": "HK"
    }
  },
  "capture_on": "2024-09-10T10:11:12Z",
  "capture": true,
  "processing": {
    "tax_amount": 10,
    "shipping_amount": 10,
    "product_type": "Official Account",
    "original_order_amount": 10,
    "open_id": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
  },
  "items": [
    {
      "name": "Item name",
      "quantity": 1,
      "unit_price": 30,
      "total_amount": 30,
      "tax_amount": 10,
      "discount_amount": 10,
      "reference": "ORDER_01234",
      "image_url": "https://some_s3bucket.com",
      "url": "https://some.website.com/item",
      "wxpay_goods_id": "1001"
    }
  ],
  "payment_ip": "90.197.169.245"
}
```

#### Response example

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

```json
{
  "id": "pay_qlccwywng5zu7mw2pwumnnjdw4",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "john.smith@example.com",
    "name": "John Smith",
    "phone": {
      "number": "564649440",
      "country_code": "+852"
    }
  },
  "processing": {
    "partner_payment_id": "e1e1edc91117561f3063e9c5a305f914",
    "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\"}"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_qlccwywng5zu7mw2pwumnnjdw4"
    }
  }
}
```

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](https://pay.weixin.qq.com/wiki/doc/api/wxpay/en/fusion_wallet/OfficialPayMent/chapter5_5.shtml) |
| Others | [Official Payment - Chapter 5.3](https://pay.weixin.qq.com/wiki/doc/api/wxpay/en/pay/OfficialPayMent/chapter5_3.shtml) |

---

## Get details about a payment

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](https://api-reference.checkout.com).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`GET` `https://{prefix}.api.checkout.com/payments/{id}`

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/payments/{id}`

### Response example

```json
{
  "id": "pay_ri6ok2tsm3yujbs3kjkg44hf34",
  "requested_on": "2022-03-21T11:21:39.0426045Z",
  "source": {
    "type": "wechatpay"
  },
  "items": [
    {
      "name": "Item name",
      "quantity": 1,
      "unit_price": 30,
      "reference": "ORDER_01234",
      "image_url": "https://some_s3bucket.com",
      "url": "https://some.website.com/item",
      "total_amount": 30,
      "tax_amount": 10,
      "discount_amount": 10,
      "wxpay_goods_id": "1001"
    }
  ],
  "amount": 50,
  "currency": "HKD",
  "payment_type": "Regular",
  "reference": "ORD-5023-4E89",
  "status": "Pending",
  "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "john.smith@example.com",
    "name": "John Smith",
    "phone": {
      "country_code": "+852",
      "number": "123456789"
    }
  },
  "shipping": {
    "address": {
      "address_line1": "123 Example St.",
      "address_line2": "Apt. 456",
      "city": "Wan Chai",
      "state": "",
      "zip": "42345",
      "country": "HK"
    }
  },
  "payment_ip": "90.197.169.245",
  "processing": {
    "partner_payment_id": "5167891a61704147404f29d6371fd702"
  },
  "_links": {
    "redirect": {
      "href": "weixin://wxpay/bizpayurl?pr=QWwHcAdzz"
    },
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_ri6ok2tsm3yujbs3kjkg44hf34"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_ri6ok2tsm3yujbs3kjkg44hf34/actions"
    }
  }
}
```

---

## Refunds and chargebacks

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

You can process a refund through the [Dashboard](https://dashboard.checkout.com) or using the [Refund API](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment.md). 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](https://api-reference.checkout.com).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

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

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/{id}/refunds`

### Request example

```json
{
  "amount": 100
}
```

### Response example

```json
{
  "action_id": "act_jf7fv3vgiu7ezjfgzvvsqobxru",
  "_links": {
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_fsud3hyoqkxencjvb5cfv6yqoe"
    }
  }
}
```

---

## Testing WeChat Pay

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

WeChat Pay does not provide a dedicated sandbox environment. To test your integration, perform low-value transactions in the production environment. You can then either refund transactions or cancel them in the WeChat Pay app during the confirmation step.

---

## WeChat Pay requirements

WeChat requires that all merchants who process payments with them display the WeChat Pay logo on their website. See the [WeChat regulations documentation](https://pay.weixin.qq.com/index.php/public/wechatpay_en/regulation_list) 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.