WeChat Mini Program - WeChat Pay

Accept WeChat Pay from your WeChat mini program. To complete the integration, you will need to interact with WeChat Mini Program API in your mini program.

Step 0. Authentication

How to obtain access token Authentication Reference

Step 1. Initialize a Payment Intent

You need to get the open_id of the shopper before proceeding with the mini_program flow. open_id refers to the unique identifier of a WeChat user in a specific mini program. It is required when confirming with mini_program flow. To get the open_id, follow the instructions below:

• Invoke wx.login , then get a code from the response.

• Invoke jscode2session from server-side with the code obtained from the last step to get the open ID of the shopper.

Then, call the Create a Payment API with the sub_appid and sub_open_id to get the data required when calling the WeChat Pay mini program API.

POST /mch-api/v1/pa/payment_intents/create

{
  "amount": "1",
  "currency": "HKD",
  "merchant_order_id": "P9297895081903",
  "payment_method": {
    "type": "wechat",
    "wechat": {
      "flow": "mini_program",
      "sub_appid": "wx7bc98d929da735fe",
      "sub_openid": "oqZa55Qo-u0cVViWMAgv_YbyXb4U"
    }
  },
  "description": "Mini Program Payment",
  "notify_url": "https://put_your_site_here/example_url"
}

• Request

REQUEST BODY	Details	Type	Required	Example
amount	Payment amount. This is the order amount you would like to charge your customer	string(32)	required
currency	Amount currency	string(32)	required	TWD
settlement_currency	Using this settlement currency in this order. If not set, we will using default settlement currency	string(3)	optional	HKD
merchant_order_id	The order ID created in merchant's order system that corresponds to this PaymentIntent. Maximum length is 32.	string(32)	required
description	The description of the order	string	required
notify_url	The URL that is used to receive the payment result notification from CBTIS	string	optional

You will get a response similar to the following.

{
  "code": 0,
  "data": {
    "order_id": "C991289984923795789123",
    "merchant_order_id": "P9297895081903",
    "amount": "1",
    "currency": "HKD",
    "create_time": "2023-08-31T04:44:05.928696203+08:00",
    "next_action": {
      "type": "call_sdk",
      "data": {
        "appId": "wx7bc98d929da735fe",
        "nonceStr": "389ldtvku2t",
        "package": "prepay_id=wx01193931618587ccd846840000",
        "paySign": "Xe8d6Tl6P5OhQz4kgk12EGfipacvVnCSHJoyNWI5TbpZ7BYfDj9/Edj+MJYezjYaAsAm6GoFAmeoewdRQZHCtaBFmVqjgyznXjhBIMteAN04JNYAS/1HdOppXFs13Eu0coUxw8qV72DDVSUTAjMWjeRMvrO0ow9lJ93STG6PuHg==",
        "signType": "RSA",
        "timeStamp": "1719833981"
      }
    },
    "status": "PENDING"
  },
  "message": "ok",
  "rid": "3647575c0e1049439e484a231864da2c"
}

Pass data in next_action you get in the previous step to WeChat Mini Program Payment API wx.requestPayment. The shopper will be redirected to the payment page to complete the payment.

Step 2. Get payment notify

Once you fill in the notify_url field when creating an order, after the user completes the payment, our system will prompt you with information about the user's completed payment.

How to verify our notify message Webhook Verify Reference

• Example Webhook

{
  "notify_type": "payment_success",
  "data": {
    "order_id": "C991289984923795789123",
    "merchant_order_id": "P9297895081903"
  }
}

Step 3. Retrieve a payment

Retrieve a Refund by ID.

POST /mch-api/v1/pa/payment_intents/query

• Example Request

{
  "order_id": "P991289984923795789123",
  "merchant_order_id": "P9297895081903"
}

• Request

REQUEST BODY	Details	Type	Required	Example
order_id	Platform order id from payment request.	string(32)	conditional (required if merchant_order_id is empty)
merchant_order_id	Merchant order id from your creation of payment.	string(32)	conditional (required if order_id is empty)

• Example Response

{
  "code": 0,
  "data": {
    "order_id": "C991289984923795789123",
    "merchant_order_id": "P9297895081903",
    "amount": "50",
    "currency": "TWD",
    "status": "SUCCEEDED",
    "create_time": "2023-08-31T04:44:05.928696203+08:00",
    "pay_time": "2023-08-31T04:44:05.928696203+08:00"
  },
  "message": "ok",
  "rid": "3647575c0e1049439e484a231864da2c"
}

• Explain of status

STATUS CODE	Details
PENDING	The Payment is pending the final result from the provider. No further action is required.
SUCCEEDED	The Payment has succeeded. The payment transaction is complete.
CANCELLED	Payment canceled or timeout, user has not completed the payment and the order has been closed.