Exchange Agreement Token

When an automatic-debit agreement becomes ACTIVE, its signed lifecycle notification contains a short-lived exchange_code. Exchange that code for the agreement_token required by subsequent automatic-debit payments.

The exchange code is valid for nine hours and can complete only one logical exchange operation.

Authentication

Use a merchant access token as described in the Authentication Reference.

Request

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

Header	Required	Description
Authorization	required	Merchant access token in the form Bearer <access_token>.
Idempotency-Key	required	A unique value for this logical exchange, up to 128 characters. Reuse the same value when retrying.
Content-Type	required	application/json.

{
  "exchange_code": "aec_L5yZ8Jwdsx3m5xjJV2rbqJ8cL4xYv-xzjxYiSoYgnNQ"
}

Field	Required	Description
exchange_code	required	The code from the ACTIVE agreement notification. Maximum length: 128 characters.

Response

{
  "code": 0,
  "message": "ok",
  "data": {
    "agreement_token": "agt_TgcdpNs8CY0XU3rARbYkXgs1tiEdBltu35bw89f_kxA",
    "merchant_agreement_id": "merchant-agreement-001",
    "status": "ACTIVE"
  },
  "rid": "4d17e795de874d6097622a1359d7d08d"
}

Store agreement_token securely. It is the credential submitted in payment_method.auto_debit.agreement_token and is not returned by agreement query APIs or future lifecycle notifications.

Safe retries

If the request succeeds on CBTIS but its response is lost, retry the same request with the same Idempotency-Key and exchange_code. CBTIS returns the original agreement_token without performing a second exchange.

• Same Idempotency-Key and same exchange_code: returns the original result.
• Same Idempotency-Key and a different exchange_code: returns 409 Conflict.
• A consumed exchange_code with a different Idempotency-Key: returns an invalid-code error.

Errors

HTTP status	Message	Meaning
400	exchange_code is required	The code is missing or longer than 128 characters.
400	invalid_or_expired_exchange_code	The code is invalid, expired, belongs to another merchant, or was already consumed by another operation.
409	Idempotency-Key is already used with another exchange_code	The idempotency key was reused for a different exchange.
409	agreement is not active	The agreement can no longer be used for automatic debit.

Next step

Use the returned token to create an automatic-debit payment for the agreement's channel:

• Alipay Plus Auto Debit Payment