Airwallex logo
Airwallex logoAirwallex logo

Accept Recurring Payments - WeChat Pay

Copy for LLMView as Markdown

WeChat requires merchants to register their products beforehand to obtain a plan_id before initiating recurring payments. Contact your Airwallex Account Manager to request WeChat recurring enablement and a plan_id. This is WeChat scheme registration, not a self-serve flag.

The linking flow you use depends on how many products (plan IDs) you have registered with WeChat Pay:

  • Flow 1: Use this flow when you have a single product (one plan ID) registered with WeChat Pay.
  • Flow 2: Use this flow when you have multiple products (multiple plan IDs) registered with WeChat Pay. You pass the relevant plan_id when you create the Payment Intent.

Flow 1: Linking with the shopper's WeChat Pay account for the first time (single product or plan ID)

Step 1: Create a Customer (Optional)

Create a customer with the Create a Customer APIAPI if the customer is new. Otherwise, this step is optional.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/pa/customers/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "2ed2d823-f8b3-416e-86db-ced8770ce217",
6    "merchant_customer_id": "9fafc2fb-4262-4ff8-a205-d60fb4781cb0",
7    "first_name": "John",
8    "last_name": "Doe",
9    "email": "[email protected]",
10    "phone_number": "+8613800138000"
11  }'

Example response:

JSON
1{
2  // ... other fields omitted.
3  "id": "cus_uspd6m9zph9g2fjvn1r",
4  "request_id": "2ed2d823-f8b3-416e-86db-ced8770ce217",
5  "merchant_customer_id": "c9fafc2fb-4262-4ff8-a205-d60fb4781cb0",
6  "first_name": "John",
7  "last_name": "Doe",
8  "email": "[email protected]",
9  "phone_number": "+8613800138000",
10  "created_at": "2024-01-15T10:30:00Z"
11}

Create a Payment Consent with the Create a Payment Consent APIAPI.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/pa/payment_consents/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "ed11e38a-7234-11ea-aa94-7fd44ffd1b89",
6    "customer_id": "cus_uspd6m9zph9g2fjvn1r",
7    "next_triggered_by": "merchant",
8    "merchant_trigger_reason": "unscheduled"
9  }'

Example response:

JSON
1{
2  // ... other fields omitted.
3  "id": "cst_sgstjgzhsh7hhmj8hr0",
4  "request_id": "ed11e38a-7234-11ea-aa94-7fd44ffd1b89",
5  "customer_id": "cus_uspd6m9zph9g2fjvn1r",
6  "next_triggered_by": "merchant",
7  "status": "REQUIRES_PAYMENT_METHOD",
8  "merchant_trigger_reason": "unscheduled",
9  "created_at": "2024-01-15T10:35:00Z"
10}

Verify the Payment Consent with the Verify a Payment Consent APIAPI to authorize the shopper's WeChat Pay account for future payments.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/pa/payment_consents/{{PAYMENT_CONSENT_ID}}/verify \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "139b8ee8-e306-47d6-8d6a-fa586967e5a9",
6    "payment_method": {
7      "type": "wechatpay",
8      "wechatpay": {
9        "flow": "qrcode"
10      }
11    },
12    "verification_options": {
13      "wechatpay": {
14        "currency": "CNY"
15      }
16    },
17    "return_url": "https://www.airwallex.com"
18  }'
  • The flow parameter can be "qrcode", "mobile_web", or "mobile_app". When flow is "mobile_web" or "mobile_app", os_type should be "ios" or "android".

Each WeChat Pay consent can only be used for subsequent payments with the same currency specified in verification_options.wechatpay.currency.

Example response:

JSON
1{
2  // ... other fields omitted.
3  "id": "cst_sgstjgzhsh7hhmj8hr0",
4  "request_id": "139b8ee8-e306-47d6-8d6a-fa586967e5a9",
5  "status": "REQUIRES_CUSTOMER_ACTION",
6  "next_action": {
7    "type": "redirect",
8    "method": "GET",
9    "url": "https://api.airwallex.com/pa/redirect/..."
10  }
11}

Redirect the shopper to the URL found in the next_action field so they can complete authorization on the WeChat Pay page.

To get the consent verification result, poll the status of the Payment Consent via the Retrieve a Payment Consent APIAPI.

In addition, Airwallex will notify you asynchronously of the Payment Consent status via webhook. Please refer to the webhook documentation to set up your webhook properly. It is recommended to subscribe to the payment_consent.verified webhook which indicates that the shopper has authorized your business to make recurring payments with their WeChat Pay wallet. Be sure to save the id returned in the response, as you will use this verified Payment Consent for future payments.

Flow 2: Linking with the shopper's WeChat Pay account for the first time (multiple products or plan IDs)

Use this flow when you have multiple products (plan IDs) registered with WeChat Pay. Instead of creating and verifying a standalone Payment Consent, you create a zero-amount Payment Intent that carries the relevant plan_id, then confirm it with an inline Payment Consent to link the shopper's WeChat Pay account.

Step 1: Create a Customer (Optional)

Create a customer with the Create a Customer APIAPI if the customer is new. Otherwise, this step is optional.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/pa/customers/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "2ed2d823-f8b3-416e-86db-ced8770ce217",
6    "merchant_customer_id": "9fafc2fb-4262-4ff8-a205-d60fb4781cb0",
7    "first_name": "John",
8    "last_name": "Doe",
9    "email": "[email protected]",
10    "phone_number": "+8613800138000"
11  }'

Step 2: Create a Payment Intent with the plan ID

Create a zero-amount Payment Intent with the Create a Payment Intent APIAPI, passing the plan_id of the product registered with WeChat Pay in payment_method_options.wechatpay.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/pa/payment_intents/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "b3d9f0a2-7c1e-4a5b-9e2d-8f6c1a4b3e10",
6    "amount": 0,
7    "currency": "CNY",
8    "merchant_order_id": "c4e0a1b3-8d2f-4b6c-a1e3-9f7d2b5c4f21",
9    "customer": {
10      "first_name": "John",
11      "last_name": "Doe",
12      "email": "[email protected]",
13      "phone_number": "+8613800138000"
14    },
15    "return_url": "https://www.airwallex.com",
16    "payment_method_options": {
17      "wechatpay": {
18        "plan_id": 118
19      }
20    }
21  }'

Step 3: Confirm the Payment Intent with WeChat Pay

Confirm the Payment Intent with the Confirm a Payment Intent APIAPI, passing the payment_consent parameter to link the shopper's WeChat Pay account for future payments.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/pa/payment_intents/{{PAYMENT_INTENT_ID}}/confirm \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "d5f1b2c4-9e3a-4c7d-b2f4-af8e3c6d5a32",
6    "payment_method": {
7      "type": "wechatpay",
8      "wechatpay": {
9        "flow": "qrcode"
10      }
11    },
12    "payment_consent": {
13      "next_triggered_by": "merchant"
14    }
15  }'
  • The flow parameter can be "qrcode", "mobile_web", or "mobile_app". When flow is "mobile_web" or "mobile_app", os_type should be "ios" or "android".

Example response:

JSON
1{
2  // ... other fields omitted.
3  "next_action": {
4    "type": "redirect",
5    "qrcode": "https://osapp.pay.weixin.qq.com/global/papay/contracts/sessions/show_code?os_session_id=20260819149294724541",
6    "method": "GET",
7    "url": "https://osapp.pay.weixin.qq.com/global/papay/contracts/sessions/show_code?os_session_id=20260819149294724541"
8  }
9  // ... other fields omitted.
10}

Redirect the shopper to the URL found in the next_action field so they can complete authorization on the WeChat Pay page.

To get the consent verification result, poll the status of the Payment Consent via the Retrieve a Payment Consent APIAPI.

In addition, Airwallex will notify you asynchronously of the Payment Consent status via webhook. Please refer to the webhook documentation to set up your webhook properly. It is recommended to subscribe to the payment_consent.verified webhook which indicates that the shopper has authorized your business to make recurring payments with their WeChat Pay wallet. Be sure to save the id returned in the response, as you will use this verified Payment Consent for future payments.

Initiating future payments

Step 1: Create a Payment Intent

Once the Payment Consent is verified by the shopper, you can use that consent for recurring payments. When you are ready to process a recurring payment, create a Payment Intent with the Create a Payment Intent APIAPI.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/pa/payment_intents/create \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "request_id": "2c343609-5561-4c39-b055-bdaf89176555",
6    "amount": 10,
7    "currency": "CNY",
8    "merchant_order_id": "order_67890",
9    "return_url": "https://www.airwallex.com"
10  }'

Example response:

JSON
1{
2  // ... other fields omitted.
3  "id": "int_hkdmr7v9rg1j58ky8re",
4  "request_id": "2c343609-5561-4c39-b055-bdaf89176555",
5  "amount": 10,
6  "currency": "CNY",
7  "merchant_order_id": "order_67890",
8  "status": "REQUIRES_PAYMENT_METHOD",
9  "created_at": "2024-01-15T11:00:00Z"
10}

Confirm the payment with the verified Payment Consent by calling the Confirm a Payment Intent APIAPI. This allows you to charge the shopper using their previously authorized WeChat Pay account without requiring them to re-authenticate.

Shell
1curl -X POST https://api.sandbox.airwallex.com/api/v1/pa/payment_intents/{{PAYMENT_INTENT_ID}}/confirm \
2  -H 'Content-Type: application/json' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -d '{
5    "payment_consent_id": "cst_sgstjgzhsh7hhmj8hr0",
6    "request_id": "a7f3e2d1-9c4b-4e8a-b5f6-3d2c1a0e9f8b"
7  }'

Step 3: Query the payment result status

To get the payment result, poll the status of the Payment Intent via the Retrieve a Payment Intent APIAPI.

In addition, Airwallex will notify you of the payment result asynchronously via webhooks. Please refer to the webhook documentation to set up your webhook accordingly. It is recommended to subscribe to the payment_intent.succeeded webhook which indicates that the shopper has paid the order.

Was this page helpful?