Alipay Plus Agreement

Before collecting an automatic debit payment, create an agreement and send the shopper to Alipay Plus to authorize it. The agreement becomes usable only after its status is ACTIVE.

Step 0. Authentication

How to obtain an access token: Authentication Reference.

Step 1. Create an agreement

POST /mch-api/v1/pa/auto_debit/agreements/create

{
  "merchant_agreement_id": "merchant-agreement-001",
  "merchant_customer_id": "customer_001",
  "return_url": "https://merchant.example.com/auto-debit/return",
  "notify_url": "https://merchant.example.com/webhooks/cbtis",
  "payment_method": {
    "type": "aplus_auto_debit",
    "aplus": {
      "terminal_type": "WAP",
      "os_type": "ANDROID",
      "user_region": "CN",
      "customer_belongs_to": "ALIPAY_CN"
    }
  }
}

Field	Required	Description
merchant_agreement_id	required	Your idempotency key for this agreement creation. Reuse the same value when retrying the request. Maximum length: 128.
merchant_customer_id	required	Your stable identifier for the shopper. Maximum length: 128.
return_url	required	Where the shopper returns after the authorization page.
notify_url	required	Receives authoritative agreement status changes.
payment_method.type	required	aplus_auto_debit.
payment_method.aplus.terminal_type	required	WEB, WAP, or APP.
payment_method.aplus.os_type	conditional	Mobile OS, such as ANDROID or IOS, for WAP and APP.
payment_method.aplus.user_region	required	Shopper's two-letter region code.
payment_method.aplus.customer_belongs_to	required	Wallet to authorize. Supported values: ALIPAY_CN, ALIPAY_HK, TRUEMONEY, GCASH, MAYA, BOOST, and DANA.

Example response:

{
  "code": 0,
  "data": {
    "agreement_id": "ADG5f4f5c8e5b6d4f3fbd9d3e8ca4f1b2a3",
    "merchant_agreement_id": "merchant-agreement-001",
    "status": "PENDING",
    "next_action": {
      "type": "redirect",
      "url": "https://wallet.example.com/authorize"
    }
  },
  "message": "ok"
}

Redirect the shopper to next_action.url. Do not charge the agreement while its status is PENDING.

If the same merchant_agreement_id is submitted again with the same request parameters, CBTIS returns the existing agreement and authorization action instead of creating another agreement. Reusing the ID with different request parameters returns 409 Conflict.

Next steps

Receive the final status through Agreement Notifications. Once it is ACTIVE, exchange the notification code for an agreement token, then create a charge using Alipay Plus Auto Debit Payment.