Table of Contents#
I. Basic Specifications#
Sandbox Environment Integration#
The sandbox environment uses the same request parameters, response parameters, signature rules, and encryption rules as the production environment.The sandbox management console also supports manual callback triggering to help merchants complete integration quickly.The sandbox environment only supports order creation, callbacks, and signature verification. No checkout page is provided.Once the sandbox integration is completed, you can create orders in the production environment to view the checkout page.
Sandbox Integration Process：
1、Log in to the merchant dashboard and switch to Sandbox Mode from the top-right corner.
2、Use the sandbox API keys to create orders.
3、After placing an order, you can manually trigger callbacks on the collection or payout order pages.
API Authentication#
The system uses the App ID + App Secret HMAC-SHA256 signature mechanism by default.1.
App ID Authentication: Every request must include the App ID in the request headers (used to identify the merchant).
2.
HMAC-SHA256 Signature (Default): The merchant App Secret is used to sign requests to ensure message integrity and prevent tampering.
3.
AES-GCM-V1 Encryption: The request body supports encryption using the aes-gcm-v1 (AES-256-GCM) algorithm to ensure data confidentiality. Plaintext mode can be enabled for special scenarios upon request.
Design Principles#
TLS (HTTPS) is required: All data must be transmitted over HTTPS to prevent man-in-the-middle attacks.
App ID is public: App ID is used only for merchant identification.
App Secret is server-side only: App Secret must never be exposed in frontend code or client repositories.
HMAC-SHA256 Signature: Ensures message integrity and authentication, preventing tampering and forgery.
Request Body Encryption (AES-GCM-V1): Protects sensitive fields or the entire request body and can be disabled upon agreement by both parties.
Replay Attack Prevention: The signature includes timestamp + nonce + request path + HTTP method + body.
Idempotency & Retry Protection: Request ID or nonce should be included in the signature, and the server should maintain a short-term nonce whitelist/blacklist.
Key Retrieval and Configuration#
Step 1：Obtain the App ID, App Secret, and apiDataKeyLog in to the merchant dashboard → System Settings → Payment Basic Configuration, and obtain the following credentials:Merchant Code: This is the App ID, used to identify the merchant application.
Merchant Secret Key: This is the App Secret, used for request signing.
Platform Public Key: This is the apiDataKey, used for AES encryption.
The App Secret and apiDataKey are displayed only once. Please store them securely.
These credentials should be stored in a secure location (such as KMS/Vault) and should not be hardcoded in the source code.
Browsers or mobile clients should not persist long-term keys. It is recommended to integrate through a backend service or use short-lived token mechanisms such as OAuth2 or JWT.
Request Signature#
Signature Principles#
HMAC-SHA256 signatures are generated using the merchant App Secret. The process is as follows:1.
Build the signing string: Concatenate according to the fixed format:
HTTP_METHOD + "\n" + REQUEST_PATH + "\n" + X-Ts + "\n" + X-Nonce + "\n" + Base64(body_bytes)
2.
Query parameters in REQUEST_PATH must be sorted alphabetically by key, and Nonce is used as the IV.
3.
Generate HMAC-SHA256: Use App Secret as the key to calculate the HMAC-SHA256 signature.
4.
Base64 Encode: Encode the HMAC result using Base64.
5.
Add Request Headers: Include X-Ts, X-Nonce, and X-Sign.
Signature Specification#
Signing String Format (Strict Order Required):signing_string = HTTP_METHOD + "\n" +
PATH?QUERY + "\n" + // Includes QUERY sorted alphabetically
X-Ts + "\n" +
X-Nonce + "\n" +
Base64(body_bytes) // Empty body should use empty string
Use appSecret as the HMAC key.
Use the HMAC-SHA256 algorithm (do not use MD5 or SHA1).
Signature results must use Base64 encoding.
Query parameters in the path must be sorted alphabetically.
Empty body should use an empty string and must not be omitted.
Important: The body used in signature calculation must always be the original plaintext JSON string before encryption, regardless of the X-Enc value.When X-Enc = none: use the original JSON string.
When X-Enc = aes-gcm-v1: still use the original plaintext JSON string (not the encrypted Base64 data).
The purpose of the signature is to verify integrity at the plaintext level.
1.
Check X-App-Id: Verify that the App ID exists and load the corresponding App Secret securely (e.g., from KMS/Vault).
2.
Validate X-Ts: Ensure the timestamp is within the allowed time window (e.g., ±300 seconds).
3.
Check X-Nonce: Verify the nonce has not been used recently. Reject duplicate nonces and cache them temporarily (e.g., Redis with 5-minute expiration).
4.
Decrypt Request Body (if X-Enc = aes-gcm-v1): Decrypt the request body first.
5.
Rebuild Signing String: Use the decrypted plaintext body to rebuild the signing string using the same rules as the client.
6.
Verify Signature: Calculate HMAC-SHA256 using App Secret and compare using constant-time comparison.
Signature verification uses the decrypted plaintext body, not the encrypted body.
Clients must also generate signatures using the plaintext body even when encryption is enabled.
Request Body Encryption#
The platform uses the merchant-configured encryption mode by default. If no encryption mode is configured, plaintext mode is used. If the request header specifies encryption, the platform will decrypt according to the header (AES-GCM-V1 is disabled by default).Encrypted Request Body Format:[IV (12 bytes)] + [Ciphertext] + [authTag (16 bytes)]
IV (Initialization Vector): 12-byte random value.
Ciphertext: Actual AES-GCM encrypted data.
authTag (Authentication Tag): 16 bytes (128 bits), automatically generated by AES-GCM to verify data integrity and authenticity.
IV does not need to be transmitted separately because it is included in the first 12 bytes of the encrypted payload.
The encrypted payload should be transmitted as raw binary data and should NOT be Base64 encoded.
Content-Type must be set to application/octet-stream.
Encryption is disabled by default. If plaintext mode is agreed upon, set X-Enc to none and ensure network security.
Encryption/decryption uses aes-gcm-v1. The AAD is the hexadecimal string of HMAC-SHA256(appId, Base64.encode(aesKey)).
Signature calculation always uses the plaintext body, even when encryption is enabled.
Encrypted: application/octet-stream
Plaintext: application/json
Idempotency Guarantee#
Create Transaction: Idempotency is guaranteed using order_no (merchant order number). Repeated requests with the same order_no will return the same result without creating duplicate transactions.
Create Payout: Idempotency is guaranteed using order_no (merchant payout order number). Repeated requests with the same order_no will return the same result without duplicate payouts.
II. Payin & Payout Process#
Modified at 2026-06-19 07:04:20
