Common Specifications

Common Request Headers

All API requests must include the following headers:

Parameter	Type	Required	Description
Content-Type	string	Yes	`application/json`
X-Request-Id	string	Yes	Request unique identifier (UUID format), used for idempotency and troubleshooting
X-Timestamp	string	Yes	Request timestamp (millisecond Unix timestamp)
X-Signature	string	Yes	Request signature (see Signature Algorithm)
Authorization	string	Yes	`Bearer {access_token}`

Common Response Format

Success Response

{
  "retCode": 20000,
  "retMsg": "Success",
  "result": {
    // Business data
  }
}

Failure Response

{
  "retCode": 40001,
  "retMsg": "Error description",
  "result": null
}

Response Fields

Parameter	Type	Description
retCode	int	Response code, `20000` indicates success
retMsg	string	Response message
result	object/null	Response data, `null` on failure

HTTP Status Codes

HTTP Status	Description	Scenario
200	Success	Business success or failure (distinguished by `retCode`)
400	Bad Request	Parameter format error, missing required field
401	Unauthorized	Token invalid or expired
403	Forbidden	IP not in whitelist, no API permission
404	Not Found	API path error
429	Too Many Requests	Rate limit triggered
500	Internal Server Error	System exception, please retry
503	Service Unavailable	System maintenance

Field Length Limits

Field Type	Max Length	Example Fields
Merchant ID	32	`merchantId`
User ID	64	`userId`, `merchantUserId`
Agreement No	64	`agreementNo`, `externalAgreementNo`
Order No	64	`outTradeNo`, `outRefundNo`
Trade No	64	`tradeNo`, `refundNo`
Amount	32	`amount.total`
Currency Code	16	`currency`
URL	512	`notifyUrl`, `returnUrl`
Description	256	`orderDesc`, `refundReason`
Title	128	`orderTitle`
Extra Params	2048	`extraParams` (JSON string)

Idempotency

Idempotency is guaranteed through business unique indexes:

Business Scenario	Idempotency Key	Unique Index
Sign Request	externalAgreementNo	(merchantId, externalAgreementNo)
Deduction Order	outTradeNo	(merchantId, outTradeNo)
Refund Request	outRefundNo	(merchantId, outRefundNo)

Notes:

X-Request-Id format requirement: UUID v4, e.g., 550e8400-e29b-41d4-a716-446655440000
Repeated requests with the same merchant order number return the result of the first request

API Timeout Recommendations

API	Recommended Timeout	Description
Sign Request	10 seconds	Sync return sign link
Sign Confirmation	10 seconds	Sync return sign status
Unsign	10 seconds	Sync return unsign result
Agreement Deduction	30 seconds	May involve on-chain operations
Deduction Refund	30 seconds	May involve on-chain operations
Query APIs	10 seconds	Sync return query result

Timeout Handling:

After timeout, call query API to confirm actual status
Deduction/refund timeout does not mean failure
Confirm final status through query or async notification

Concurrency Handling

Same Agreement Concurrent Deductions

Same agreement supports concurrent deduction requests
Each deduction needs different outTradeNo
Limit verification is real-time; concurrent requests may be rejected if exceeding quota

Same Order Repeated Requests

Requests with same outTradeNo are treated as the same transaction
After first request succeeds, repeated requests return the first result (idempotent)
After first request fails, use a new outTradeNo to retry

Transaction Status Flow

Deduction Status

                    ┌─────────────┐
                    │  PROCESSING │
                    └──────┬──────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
           ▼               ▼               ▼
    ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
    │   SUCCESS   │ │   FAILED    │ │   TIMEOUT   │
    └─────────────┘ └─────────────┘ └─────────────┘

Status	Description	Follow-up Actions
PROCESSING	Deduction in progress	Wait for notification or query
SUCCESS	Deduction successful	Can initiate refund
FAILED	Deduction failed	Retry with new order number
TIMEOUT	Deduction timeout	Query to confirm, then decide

Refund Status

                    ┌─────────────┐
                    │  PROCESSING │
                    └──────┬──────┘
                           │
                ┌──────────┴──────────┐
                │                     │
                ▼                     ▼
         ┌─────────────┐       ┌─────────────┐
         │   SUCCESS   │       │   FAILED    │
         └─────────────┘       └─────────────┘

Status	Description	Follow-up Actions
PROCESSING	Refund in progress	Wait for notification or query
SUCCESS	Refund successful	Funds returned to user
FAILED	Refund failed	Check reason, retry with new refund number

Refund Notes:

Refund amount cannot exceed refundable amount
Same transaction supports multiple partial refunds
Used quota is restored after successful refund

Rate Limiting

Rate Limit Strategy

API Type	Dimension	Threshold	Description
Sign Request	Merchant + User	10/minute	Same merchant for same user
Agreement Deduction	Merchant	1000/second	Merchant-level QPS
Agreement Deduction	Agreement	10/second	Single agreement frequency
Query APIs	Merchant	5000/second	All query APIs shared
Refund API	Merchant	500/second	Merchant-level refund rate

Rate Limit Response

HTTP status 429 with body:

{
  "retCode": 42900,
  "retMsg": "Too many requests, please try again later",
  "result": {
    "retryAfter": 1000
  }
}

Handling Recommendations

Exponential Backoff: Retry with delays (1s, 2s, 4s, 8s)
Request Merging: Use list query API instead of multiple single queries
Async Processing: Use message queue for peak shaving in high concurrency
Monitoring: Monitor 429 response ratio, adjust strategy accordingly

Agreement Type Description

Agreement type (agreementType) defines the deduction mode of agreement payment, affecting deduction frequency, limit configuration, and agreement lifecycle.

Agreement Type Comparison

Type	Description	Applicable Scenarios	Deduction Frequency	Limit Configuration Support	Agreement Lifecycle
CYCLE	Periodic deduction	Fixed periodic deduction for subscription scenarios	Periodic deduction (e.g., monthly)	Single limit + Period limits (DAY/WEEK/MONTH/YEAR)	Long-term validity, expires upon term end or cancellation
NON_CYCLE	Non-periodic deduction	Non-fixed deduction cycle, merchant can initiate anytime	Irregular deduction (triggered by actual consumption)	Single limit + Period limits (DAY/WEEK/MONTH/YEAR)	Long-term validity, expires upon term end or cancellation
SINGLE	Single authorization	One-time valid, agreement automatically expires after deduction	One-time deduction only	Single limit only	Short-term validity, automatically expires after successful deduction

Typical Scenario Examples

CYCLE - Periodic Deduction

Membership Subscription: Video membership, music subscription, gym monthly card, cloud service annual fee
Bill Payment: Monthly utility bills, property fees, monthly mobile plan fees
Characteristics: Fixed deduction time, amounts may be same or different

NON_CYCLE - Non-Periodic Deduction

Transportation Services: Ride-hailing, parking fees, ETC tolls, public transit
Food & Beverage: Food delivery orders, restaurant membership deduction
Lifestyle Services: Laundry, repair, car rental
Characteristics: Triggered by actual consumption, irregular deduction frequency and amounts

SINGLE - Single Authorization

Pre-authorization Scenarios: Hotel deposits, car rental deposits
One-time Deduction: One-time authorized payment, temporary deduction
Characteristics: Agreement automatically expires after deduction, no manual cancellation needed

Limit Configuration Description

CYCLE and NON_CYCLE Types:

Support Single Limit (singleLimit): Maximum amount per deduction
Support Period Limits (periodLimits):
- DAY: Daily accumulated deduction limit
- WEEK: Weekly accumulated deduction limit
- MONTH: Monthly accumulated deduction limit
- YEAR: Yearly accumulated deduction limit
Multiple period limits can be configured simultaneously, platform validates all limits

SINGLE Type:

Only supports Single Limit (singleLimit)
Period limits not supported (as agreement expires after deduction)

Agreement Lifecycle Comparison

Operation	CYCLE	NON_CYCLE	SINGLE
After Sign	SIGNED status, can deduct	SIGNED status, can deduct	SIGNED status, can deduct
First Deduction	Remains SIGNED	Remains SIGNED	Automatically becomes UNSIGNED (agreement expires)
Multiple Deductions	Supported	Supported	Not supported (expires after first deduction)
User Cancellation	Supported	Supported	Not applicable (auto-expires after deduction)
Merchant Cancellation	Supported	Supported	Not applicable (auto-expires after deduction)
Agreement Expiration	Becomes EXPIRED	Becomes EXPIRED	Not applicable (auto-expires after deduction)

Usage Recommendations

Choose Appropriate Type:
- Subscription-based business: Choose CYCLE
- On-demand consumption business: Choose NON_CYCLE
- One-time authorization: Choose SINGLE
Limit Configuration Principles:
- Single limit should cover most transaction scenarios
- Period limits prevent excessive short-term deductions
- CYCLE type recommended to configure monthly limit
- NON_CYCLE type recommended to configure daily limit
Agreement Management:
- CYCLE/NON_CYCLE agreements require active cancellation or await expiration
- SINGLE agreements auto-expire after deduction, no management needed
- Recommend setting reasonable validity period (signValidTime) for long-term agreements

Common Request Headers​

Common Response Format​

Success Response​

Failure Response​

Response Fields​

HTTP Status Codes​

Field Length Limits​

Idempotency​

API Timeout Recommendations​

Concurrency Handling​

Same Agreement Concurrent Deductions​

Same Order Repeated Requests​

Transaction Status Flow​

Deduction Status​

Refund Status​

Rate Limiting​

Rate Limit Strategy​

Rate Limit Response​

Handling Recommendations​

Agreement Type Description​

Agreement Type Comparison​

Typical Scenario Examples​

Limit Configuration Description​

Agreement Lifecycle Comparison​

Usage Recommendations​