Skip to content

WeChat Pay Beta

Last updated: 16th September 2022

Start accepting payments using WeChat Pay, a popular digital wallet service in China.

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.

To learn more, reach out to your Customer Success 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

QR code 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.

Request a payment

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

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    {
    "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",
    "success_url": "https://example.com",
    "reference": "ORD-5023-4E89",
    "processing_channel_id": "{{processing-channel-id}}",
    "customer": {
    "name": "Cecilia Chapman",
    "email": "c.chapman@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": "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": "some description about item",
    "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.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    {
    "id": "pay_gdbok753fk3ebk4dpq7xqq72te",
    "status": "Pending",
    "reference": "ORD-5023-4E89",
    "customer": {
    "id": "cus_ujs5uvwcshhujllodxegkknwou",
    "email": "c.chapman@example.com",
    "name": "Cecilia Chapman",
    "phone": {
    "number": "564649440",
    "country_code": "+852"
    }
    },
    "processing": {
    "partner_payment_id": "fedc4728c87d0709fceaf1c8b6945cce"
    },
    "_links": {
    "self": {
    "href": "https://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 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 Customer Success Manager for more information.

    Request a payment

    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

      Request example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      24
      25
      26
      27
      28
      29
      30
      31
      32
      33
      34
      35
      36
      37
      38
      39
      40
      41
      42
      43
      44
      45
      46
      47
      48
      49
      50
      51
      52
      53
      54
      55
      56
      57
      58
      {
      "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",
      "success_url": "https://example.com",
      "reference": "ORD-5023-4E89",
      "processing_channel_id": "{{processing-channel-id}}",
      "customer": {
      "name": "Cecilia Chapman",
      "email": "c.chapman@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": "2019-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": "some description about item",
      "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.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      {
      "id": "pay_txjup4rkax2utcifmwzfjgzsia",
      "status": "Pending",
      "reference": "ORD-5023-4E89",
      "customer": {
      "id": "cus_ujs5uvwcshhujllodxegkknwou",
      "email": "c.chapman@example.com",
      "name": "Cecilia Chapman",
      "phone": {
      "number": "564649440",
      "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://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 operatingSDK documentation

      Hong Kong, Japan, Macau

      In-App Pay – Chapter 6.4

      Others

      In-App Pay - Chapter 6.3

      Mini program payment

      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.

      Request a payment

      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

        Request example

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        24
        25
        26
        27
        28
        29
        30
        31
        32
        33
        34
        35
        36
        37
        38
        39
        40
        41
        42
        43
        44
        45
        46
        47
        48
        49
        50
        51
        52
        53
        54
        55
        56
        57
        58
        59
        {
        "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",
        "success_url": "https://example.com",
        "reference": "ORD-5023-4E89",
        "processing_channel_id": "{{processing-channel-id}}",
        "customer": {
        "name": "Cecilia Chapman",
        "email": "c.chapman@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": "2019-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": "some description about item",
        "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.

        1
        2
        3
        4
        5
        6
        7
        8
        9
        10
        11
        12
        13
        14
        15
        16
        17
        18
        19
        20
        21
        22
        23
        {
        "id": "pay_i3pquwatsxuufih4ceqtany7ga",
        "status": "Pending",
        "reference": "ORD-5023-4E89",
        "customer": {
        "id": "cus_ujs5uvwcshhujllodxegkknwou",
        "email": "c.chapman@example.com",
        "name": "Cecilia Chapman",
        "phone": {
        "number": "564649440",
        "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://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 operatingSDK documentation

        Hong Kong, Japan, Macau

        Mini Program Pay - Chapter 7

        Others

        In-App Pay - Chapter 6

        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 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

          Request example

          1
          2
          3
          4
          5
          6
          7
          8
          9
          10
          11
          12
          13
          14
          15
          16
          17
          18
          19
          20
          21
          22
          23
          24
          25
          26
          27
          28
          29
          30
          31
          32
          33
          34
          35
          36
          37
          38
          39
          40
          41
          42
          43
          44
          45
          46
          47
          48
          49
          50
          51
          52
          53
          54
          55
          56
          57
          58
          59
          {
          "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",
          "success_url": "https://example.com",
          "reference": "ORD-5023-4E89",
          "processing_channel_id": "{{processing-channel-id}}",
          "customer": {
          "name": "Cecilia Chapman",
          "email": "c.chapman@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": "2019-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": "some description about item",
          "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.

          1
          2
          3
          4
          5
          6
          7
          8
          9
          10
          11
          12
          13
          14
          15
          16
          17
          18
          19
          20
          21
          22
          23
          {
          "id": "pay_qlccwywng5zu7mw2pwumnnjdw4",
          "status": "Pending",
          "reference": "ORD-5023-4E89",
          "customer": {
          "id": "cus_ujs5uvwcshhujllodxegkknwou",
          "email": "c.chapman@example.com",
          "name": "Cecilia Chapman",
          "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://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 operatingSDK documentation

          Hong Kong, Japan, Macau

          Official Payment - Chapter 5.5

          Others

          Official Payment - Chapter 5.3

          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.

            get

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

            Response example

            1
            2
            3
            4
            5
            6
            7
            8
            9
            10
            11
            12
            13
            14
            15
            16
            17
            18
            19
            20
            21
            22
            23
            24
            25
            26
            27
            28
            29
            30
            31
            32
            33
            34
            35
            36
            37
            38
            39
            40
            41
            42
            43
            44
            45
            46
            47
            48
            49
            50
            51
            52
            53
            54
            55
            56
            57
            58
            {
            "id": "pay_ri6ok2tsm3yujbs3kjkg44hf34",
            "requested_on": "2022-03-21T11:21:39.0426045Z",
            "source": {
            "type": "wechatpay"
            },
            "items": [{
            "name": "Item name",
            "quantity": 1,
            "unit_price": 30,
            "reference": "some description about item",
            "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": "c.chapman@example.com",
            "name": "Cecilia Chapman",
            "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"
            }
            },
            "payment_ip": "90.197.169.245",
            "processing": {
            "partner_payment_id": "5167891a61704147404f29d6371fd702"
            },
            "_links": {
            "redirect": {
            "href": "weixin://wxpay/bizpayurl?pr=QWwHcAdzz"
            },
            "self": {
            "href": "https://api.sandbox.checkout.com/payments/pay_ri6ok2tsm3yujbs3kjkg44hf34"
            },
            "actions": {
            "href": "https://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 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

              Request example

              1
              2
              3
              {
              "amount": 100
              }

              Response example

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

              Supported webhooks

              You may receive the following webhooks when using WeChat Pay:

              WebhookDescription

              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 2 hours.

              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.


              Testing WeChat Pay

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

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

              1. Create a WeChat Pay payment transaction based on a payment type as described in this documentation.
              2. Check the transaction response in the sandbox environment.
              3. 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.
              4. Complete the payment transaction and check the result status.

              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 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.