2026/05/08

Release Date	Description of Product	Version
2026/03/17	Version V1.0 has been released, supporting automatic aggregation, displaying payment addresses via QR codes, and automated strategies for dynamic payment addresses.	V1.0.0
2026/05/08	Version V1.1 has been released, adding payout/settlement functionality for merchant fund settlement to RD Convert wallet.	V1.1.0

Integration process

Environment Setup

Activate Merchant Account and Obtain API Keys
1. Complete merchant account setup and configuration in the operations/management backend.
2. Generate the following authentication information in the backend:
  1. AppId: Merchant Application ID
  2. AppSecret: Merchant Application Secret (Server-side only, must not be disclosed)
  3. ApiKey: Used for basic authentication and access control
3. Configure IP whitelist (Recommended to only allow merchant server egress IP).
Select Environment and Complete Connectivity Test
1. Use the development environment for integration testing and verification.
2. After successful testing, switch to the production environment.
Integrate Core APIs
1. Order Management: Create Order, Query Order, Query Reconciliation Statement.
2. Refund Management: Create Refund, Query Refund.
3. Payout Management: Create Payout, Query Payout.
Integrate Callback Notifications (Webhook)
1. Configure Order/Refund/Payout Status Notification URL in the merchant backend.
2. Implement the notification processing interface, supporting:
  1. Verify Signature (Required)
  2. Idempotent Processing (Required)
  3. Retry Reception
Integration Testing and Go-Live
1. Perform integration testing according to business scenarios (e.g., placing an order, successful payment, timeout cancellation, successful/failed refund).
2. After small-scale verification in the production environment, gradually increase traffic.

Basic Environment

Base URL
- Development environment: https://gw.uat.rdezlink.tech
- Production environment: https://gw.rd.group
Protocol and format
- Protocol: HTTPS
- Data format: JSON
- Character encoding: UTF-8
- API version: v1 (reflected in the URL as /api/v1/...)
Standard for amount fields (important)
- All fields related to amounts, fees, balances, etc. must be transmitted as strings in JSON to avoid precision loss.
- For example: "amount": "100.00"
- Do not use "amount": 100.00

Authentication Security

Authentication Method and Signature Mechanism (Mandatory): All API requests must be made via HTTPS and include the following fields in the header for authentication and tamper-proof verification: Request Header Fields:

Field Name	Type	Required	Description
`X-Api-Key`	String	yes	Merchant API Key (Platform Assignment)
`X-App-Id`	String	yes	Merchant Application Identifier
`X-Timestamp`	String	yes	Timestamp (milliseconds, 13 digits), used to prevent replay attacks.
`X-Nonce`	String	yes	Random string, recommended length ≥ 16
`X-Signature`	String	yes	Request Signature (HMAC-SHA256)

Signature algorithm description (recommended implementation):

Concatenate the following items in order into a string signPayload:
1. HTTP method (uppercase, e.g., POST)
2. Request path (without domain, e.g., /api/v1/order/create)
3. X-App-Id
4. X-Timestamp
5. X-Nonce
6. Request body raw JSON string (remove extra spaces, keep it exactly as actually sent)
Use AppSecret as the key to perform HMAC-SHA256 on signPayload; output the result as hexadecimal or Base64, which becomes X-Signature.
The platform server will verify the signature using the same rules:

Verify X-Timestamp is within the allowed time window (for example ±5 minutes). Verify X-Nonce has not been reused (platform stores nonces for deduplication to prevent replay attacks). Verify X-Signature is correct. Example pseudocode (for illustration only):

// Header
X-Api-Key: your-api-key
X-App-Id: your-app-id
X-Timestamp: "1710576000"
X-Nonce: "random-string-123456"
X-Signature: "计算后的签名字符串"

The platform provides signature examples or SDKs for languages such as Java/Go/Node/PHP.

IP Whitelist

Supports IP whitelist configuration in the following formats (set in the merchant management backend):

Single IP: 192.168.1.100
Multiple IPs: 192.168.1.100,192.168.1.110,192.168.1.120

Security Recommendations:

Only allow access from the merchant server’s egress IP to prevent exposing the API Key to the frontend or uncontrolled environments.
Avoid directly calling interfaces in environments such as browsers and mobile devices.

General Response Format: All interfaces return a unified response structure:

{
  "code": "0000",
  "msg": "success",
  "data": {},
  "traceId": "xxx"
}

code: response code, 0000 indicates success, non-0000 indicates failure.
msg: Response message with a brief error reason.
data: The content of the business data.
traceId: Request a trace ID for easy troubleshooting (please provide this when troubleshooting with the platform).

Response Code Examples Below are the primary response codes discussed in this document. A complete list of error codes may be extended by the platform in the future.

code	Description
0000	Success
1000	The user does not exist
1010	Authentication failed
1015	The order does not exist
1020	Risk control refuses
3001	Invalid wallet address format
3002	This blockchain network is not supported at this time
3003	The balance is not enough to cover on-chain gas fees
3004	Create orders repeatedly
3005	The refund amount exceeds the refundable amount of the order
3006	The order has expired and cannot be paid

Order Management

Create Order

Create a new billing order and generate a payment address and checkout URL.

URL：POST /api/v1/order/create
Content-Type：application/json

Request parameters

Field Name	Type	Maximum Length	Required	Description
`bizNo`	String	128	yes	Merchant business order number, used for idempotency control, unique within the same merchant.
`amount`	String	64	yes	Order amount, must be greater than 0, minimum “`0.01`”.
`currency`	String	8	yes	Order currency, please use `USD` currently.
`expireSeconds`	Integer	4	no	Order expiration time (seconds). If not provided, the system default value will be used (e.g., 600 seconds).
`userInfo`	Object	-	Conditional	User information; required when the order amount is ≥ 1000 USD.
`productInfo`	Object	-	yes	Product information
`successUrl`	String	256	no	Front-end notification URL for order status (used when the front-end needs to be aware of status changes).
`failureUrl`	String	256	no	Front-end notification URL for order status (used when the front-end needs to be aware of status changes).

userInfo Field Description：

Field Name	Type	Maximum Length	Required	Description
`clientId`	String	64	yes	Merchant-side user identification
`name`	String	128	yes	User name
`address`	String	512	yes	User address information
`certType`	String	32	no	Document type
`certNo`	String	32	no	ID number
`email`	String	128	no	User email
`phone`	String	32	no	User mobile phone number

productInfo Field Description：

Field Name	Type	Maximum Length	Required	Description
`productName`	String	128	yes	Product Name
`productLink`	String	512	no	product Link
`quantity`	Integer	11	no	Purchase Quantity
`description`	String	1024	yes	Product Description

Request Example

{
  "bizNo": "BIZ202401010001",
  "amount": "100.00",
  "currency": "USD",
  "expireSeconds": 3600,
  "userInfo": {
    "clientId": "USER001",
    "name": "zhangsan",
    "address": "中国深圳南山xxxx",
    "email": "user@example.com"
  },
  "productInfo": {
    "productName": "Premium Membership",
    "productLink": "https://example.com/product/123",
    "quantity": 1,
    "description": "1 month premium membership"
  },
  "successUrl": "https://merchant.example.com/callback/success",
  "failureUrl": "https://merchant.example.com/callback/failure"
}

Response Parameters

Field Name	Type	Maximum Length	Description
`orderId`	String	64	System Order ID
`bizNo`	String	128	Merchant Business Order Number
`amount`	String	64	Order Amount (in string format)
`status`	String	16	Order Status, see “Order Status Description”
`expireTime`	Date	-	Expiration Time (in ISO8601 format)
`receiveAddress`	List	-	Receiving Address List (multiple records will be returned for multi-chain and multi-currency scenarios)
`cashierUrl`	String	256	Cashier URL (can be redirected to this page to complete payment)

receiveAddress Field Description：

Field Name	Type	Maximum Length	Description
`address`	String	64	Wallet Address
`chain`	String	16	Chain Type (e.g., `ETH` / `TRX` / `SOL` / `POLYGON`)
`tokenCurrency`	List<String>	-	Supported Token Currencies (e.g., [“`USDT`”])

Multi-chain Payment Instructions:

The system supports returning multiple receiving addresses (for different chains/currencies).

It is recommended that the merchant’s front end, when displaying at the checkout, guide users to select only one chain to complete the payment, avoiding splitting it into multiple transactions.

By default, the system accumulates the received amounts on an order basis. When the cumulative amount of multiple valid receipts under the same order reaches or exceeds the expected amount, the payment can be considered successful. For other strategies, please confirm with the platform.

Response Example

{
  "code": "0000",
  "msg": "success",
  "data": {
    "orderId": "O202401010001",
    "bizNo": "BIZ202401010001",
    "amount": "100.00",
    "status": "PENDING",
    "expireTime": "2024-01-01T12:00:00Z",
    "receiveAddress": [
      {
        "address": "0x1234...5678",
        "chain": "ETH",
        "tokenCurrency": ["USDT","USDC"]
      },
      {
        "address": "TK1234...5678",
        "chain": "TRX",
        "tokenCurrency": ["USDT","USDC"]
      }
    ],
    "cashierUrl": "https://cashier.example.com/pay?order=xxx"
  },
  "traceId": "trace123"
}

Query Order

Query order details based on the system order ID.

URL：POST /api/v1/order/query
Content-Type：application/json

Request Parameters

Field Name	Type	Maximum Length	Required	Description
`orderId`	String	64	yes	System Order ID

Request Example

{
  "orderId": "O202401010001"
}

Response Parameters

Field Name	Type	Maximum Length	Description
`orderId`	String	64	System Order ID
`bizNo`	String	128	Merchant Business Order Number
`orderAmount`	String	64	Order Amount (String)
`actualAmount`	String	64	Actual Received Amount (String)
`currency`	String	8	Order Currency
`chain`	String	16	Chain Type
`receiveCurrency`	String	16	Receiving Currency
`receiveAddress`	String	64	Receiving Address
`txHash`	String	64	Blockchain Transaction Hash
`status`	String	16	Order Status
`orderTime`	Date	-	Order Time
`finishTime`	Date	-	Completion Time

Order Status Description

Status	Description
`PENDING`	Pending Payment
`AMOUNT_MISMATCH`	Amount Mismatch
`PAY_SUCCESS`	Payment Successful
`PAY_FAIL`	Payment Failed
`TIMEOUT`	Timed Out
`COMPLETED`	Settled
`REFUNDED`	Refunded

Response Example

{
  "code": "0000",
  "msg": "success",
  "data": {
    "orderId": "O202401010001",
    "bizNo": "BIZ202401010001",
    "orderAmount": "100.00",
    "actualAmount": "100.00",
    "currency": "USD",
    "chain": "ETH",
    "receiveCurrency": "USDT",
    "receiveAddress": "0x1234...5678",
    "txHash": "0xabc123...def456",
    "status": "PAY_SUCCESS",
    "orderTime": "2024-01-01T10:00:00Z",
    "finishTime": "2024-01-01T10:30:00Z"
  },
  "traceId": "trace123"
}

Query Statement

Query order reconciliation information by paging according to the order placement time range.

URL：POST /api/v1/order/queryRecon
Content-Type：application/json

Request Parameters

Field Name	Type	Maximum Length	Required	Description
`startTime`	Date	-	yes	Query start time (inclusive), based on the order placement time.
`endTime`	Date	-	yes	Query end time (exclusive), based on order placement time.
`pageId`	Int	11	yes	Page number, starting from 1.
`pageSize`	Int	11	yes	Page size, maximum 1000 entries.

Request Example

{
  "startTime": "2024-01-01T10:00:00Z",
  "endTime": "2024-01-03T10:30:00Z",
  "pageId": 1,
  "pageSize": 1000
}

Response Parameters

Field Name	Type	Maximum Length	Description
`total`	Int	11	Total number of orders
`orderList`	List\<Object>	-	Statement List

Statement detail fields

Field Name	Type	Maximum Length	Description
`orderId`	String	64	System Order ID
`bizNo`	String	128	Merchant Business Order Number
`orderAmount`	String	64	Order Amount
`actualAmount`	String	64	Actual Received Amount
`currency`	String	8	Order Currency
`chain`	String	16	Chain Type
`receiveCurrency`	String	16	Receiving Currency
`receiveAddress`	String	64	Receiving Address
`txHash`	String	64	Blockchain Transaction Hash
`status`	String	16	Order Status
`orderTime`	Date	-	Order Placement Time
`finishTime`	Date	-	Payment Completion Time
`settleTime`	Date	-	Settlement Time
`settleAmount`	String	64	Settlement Amount
`feeList`	List	-	Fee Details List

Fee Details Fields

Field Name	Type	Maximum Length	Description
`feeAmount`	String	64	Fee Amount
`feeCurrency`	String	16	Fee Currency
`feeType`	String	16	Fee Type: WITHDRAW_FEE

Response Example

{
  "code": "0000",
  "msg": "success",
  "data": {
    "total": 100,
    "orderList": [
      {
        "orderId": "O202401010001",
        "bizNo": "BIZ202401010001",
        "userId": "U001",
        "orderAmount": "100.00",
        "actualAmount": "100.00",
        "currency": "USD",
        "chain": "ETH",
        "receiveCurrency": "USDT",
        "receiveAddress": "0x1234...5678",
        "txHash": "0xabc123...def456",
        "status": "PAY_SUCCESS",
        "orderTime": "2024-01-01T10:00:00Z",
        "finishTime": "2024-01-01T10:30:00Z",
        "settleTime": "2024-01-02T10:30:00Z",
        "settleAmount": "90.00",
        "feeList": [
          {
            "feeAmount": "10.00",
            "feeCurrency": "USDT",
            "feeType": "WITHDRAW_FEE"
          }
        ]
      }
    ]
  },
  "traceId": "trace123"
}

Refund Management

Create Refund

Create a refund request for a specified order, only supporting full refunds now (partial refunds will be supported later. Actual capabilities are subject to platform configuration). To prevent fund theft, refunds will be returned to the original payment method.

URL：POST /api/v1/refund/create
Content-Type：application/json

Request Parameters

Field Name	Type	Maximum Length	Required	Description
`orderId`	String	64	yes	Original Order ID
`reason`	String	512	yes	Refund Reason

Request Example

{
  "orderId": "O202401010001",
  "reason": "User requests a refund"
}

Response Parameters

Field Name	Type	Maximum Length	Description
`refundId`	String	64	Refund ID
`orderId`	String	64	Original Order ID
`refundAmount`	String	64	Refund Amount
`feeAmount`	String	64	Refund Fee Amount
`currency`	String	8	Currency Type
`status`	String	16	Refund Status, find more

Response Example

{
  "code": "0000",
  "msg": "success",
  "data": {
    "refundId": "R202401010001",
    "orderId": "O202401010001",
    "refundAmount": "100.00",
    "feeAmount": "10.00",
    "currency": "USDT",
    "status": "PROCESSING"
  },
  "traceId": "trace123"
}

Query Refund

Query refund information by Refund ID or Order ID.

URL：POST /api/v1/refund/query
Content-Type：application/json

Request Parameters Choose one of the two parameters: Either refundId or orderId must be provided, and only one can be provided.

Field Name	Type	Maximum Length	Required	Description
`refundId`	String	64	no\*	Refund ID (choose either this or `orderId`)
`orderId`	String	64	no\*	Original order ID (choose either this or `refundId`)

Request Example

{
  "refundId": "R202401010001"
}

Response Parameters

Field Name	Type	Maximum Length	Description
`refundId`	String	64	Refund ID
`orderId`	String	64	Original Order ID
`refundAmount`	String	64	Refund Amount
`feeAmount`	String	64	Refund Fee Amount
`currency`	String	8	Currency
`chain`	String	16	Chain Type
`toAddress`	String	64	Refund Target Address
`txHash`	String	64	Blockchain Transaction Hash
`status`	String	16	Refund Status
`reason`	String	512	Refund Reason

Refund Status Description

Status	Description
`PROCESSING`	Processing
`SUCCESS`	Success
`FAILED`	Failed

Response Example

{
  "code": "0000",
  "msg": "success",
  "data": {
    "refundId": "R202401010001",
    "orderId": "O202401010001",
    "refundAmount": "100.00",
    "feeAmount": "10.00",
    "currency": "USDT",
    "chain": "ETH",
    "toAddress": "0x9876...5432",
    "txHash": "0xdef456...abc123",
    "status": "SUCCESS",
    "reason": "用户申请退款"
  },
  "traceId": "trace123"
}

Payout Management

Create Payout

Initiate a merchant fund settlement to the RD Convert wallet.

URL：POST /api/v1/payout/create
Content-Type：application/json

Request Parameters

Field Name	Type	Maximum Length	Required	Description
`merchantOrderNo`	String	128	yes	Merchant business order number, used for idempotency control, unique within the same merchant.
`chain`	String	16	yes	Chain type (e.g., `ETH` / `TRX` / `SOL` / `POLYGON`).
`currency`	String	8	yes	Payout currency (e.g., `USDT`).
`amount`	String	64	yes	Payout amount, must be greater than the minimum (default `10`).

Request Example

{
  "merchantOrderNo": "PO202401010001",
  "chain": "ETH",
  "currency": "USDT",
  "amount": "1000.00"
}

Response Parameters

Field Name	Type	Maximum Length	Description
`payoutId`	String	64	System Payout ID
`merchantOrderNo`	String	128	Merchant Business Order Number
`amount`	String	64	Payout Amount (in string format)
`currency`	String	8	Payout Currency
`chain`	String	16	Chain Type
`status`	String	16	Payout Status, see “Payout Status Description”

Response Example

{
  "code": "0000",
  "msg": "success",
  "data": {
    "payoutId": "PO202401010001",
    "merchantOrderNo": "PO202401010001",
    "amount": "1000.00",
    "currency": "USDT",
    "chain": "ETH",
    "status": "INIT"
  },
  "traceId": "trace123"
}

Query Payout

Query payout information by Payout ID or merchant business order number.

URL：POST /api/v1/payout/query
Content-Type：application/json

Request Parameters Choose one of the two parameters: Either payoutId or merchantOrderNo must be provided.

Field Name	Type	Maximum Length	Required	Description
`payoutId`	String	64	no*	Payout ID (choose either this or `merchantOrderNo`)
`merchantOrderNo`	String	128	no*	Merchant business order number (choose either this or `payoutId`)

Request Example

{
  "payoutId": "PO202401010001"
}

Response Parameters

Field Name	Type	Maximum Length	Description
`payoutId`	String	64	System Payout ID
`merchantOrderNo`	String	128	Merchant Business Order Number
`amount`	String	64	Payout Amount (in string format)
`currency`	String	8	Payout Currency
`chain`	String	16	Chain Type
`toAddress`	String	64	Payout Destination Address
`txHash`	String	64	Blockchain Transaction Hash
`convertOrderNo`	String	64	RD Convert Order Number
`status`	String	16	Payout Status

Payout Status Description

Status	Description
`INIT`	Initialized
`PROCESSING`	Processing
`SUCCESS`	Success
`FAILED`	Failed

Response Example

{
  "code": "0000",
  "msg": "success",
  "data": {
    "payoutId": "PO202401010001",
    "merchantOrderNo": "PO202401010001",
    "amount": "1000.00",
    "currency": "USDT",
    "chain": "ETH",
    "toAddress": "0x9876...5432",
    "txHash": "0xdef456...abc123",
    "convertOrderNo": "CO202401010001",
    "status": "SUCCESS"
  },
  "traceId": "trace123"
}

Status Notification (Webhook, with Signature)

Overview When the order, refund, or payout status changes, the system sends a status notification to the notification URL configured by the merchant through an HTTPS POST request, and the signature generation and basic legitimacy verification of the callback request are handled by the gateway. Merchants need to configure the URL for receiving notifications in the management backend, only support the HTTPS protocol, and implement processing logic on the server side. All notification requests will carry a signature header and merchants must complete signature verification before proceeding with the transaction. Notification Request Headers Similar to business requests, callback notifications will also carry the following Headers:

Field Name	Type	Required	Description
`X-Api-Key`	String	yes	Merchant API Key (Platform Assignment)
`X-App-Id`	String	yes	Merchant Application Identifier
`X-Timestamp`	String	yes	Timestamp, used to prevent replay attacks
`X-Nonce`	String	yes	Random string
`X-Signature`	String	yes	Callback signature (HMAC-SHA256)

The signature for callback requests is uniformly generated by the gateway. The signature algorithm is identical to the business request signature algorithm described in Section 3.1. The fixed concatenation rule for the signature payload is as follows: POST + full callback URL path + X-App-Id + X-Timestamp + X-Nonce + original JSON string of the callback body The signature algorithm is the same as in Section 3.1, and the body contains the JSON content of the notification. The merchant side must use its own stored AppSecret to verify the signature of the notification and reject requests that fail verification, returning a 401 status code.

Note: The difference here is that the full callback URL path is used, i.e., the complete URL for receiving notifications.

Trigger Scenarios

Trigger Scenario	Description
Order Payment Successful	User completes payment, order status changes to `PAY_SUCCESS`
Order Payment Failed	Order is actively canceled, status changes to `PAY_FAILED`
Order Expired	Order not paid within timeout period, system automatically cancels, status is `TIMEOUT`
Refund Successful	Refund processing completed, status changes to `SUCCESS`
Refund Failed	Refund processing failed, status changes to `FAILED`
Payout Successful	Payout processing completed, status changes to `SUCCESS`
Payout Failed	Payout processing failed, status changes to `FAILED`

Order Status Notification

Request Method:
- URL: Notification URL configured by the merchant
- Method: POST
- Content-Type：application/json

Request Parameters (Order Notification)

Field Name	Type	Maximum Length	Description
`orderId`	String	64	System Order ID
`bizNo`	String	128	Merchant Business Order Number
`orderAmount`	String	64	Order Amount
`actualAmount`	String	64	Actual Received Amount
`currency`	String	8	Currency Type
`receiveCurrency`	String	16	Currency Received on the Chain
`receiveAddress`	String	64	Address Where Money is Received on the Chain
`chain`	String	16	Chain Type
`status`	String	16	Order Status (Consistent with other)
`blockHeight`	Long	-	Block Height for On-Chain Verification

Request Example

{
  "orderId": "O202401010001",
  "bizNo": "BIZ202401010001",
  "orderAmount": "100.00",
  "actualAmount": "100.00",
  "currency": "USD",
  "receiveCurrency": "USDT",
  "receiveAddress": "0x123...xyz",
  "chain": "ETH",
  "status": "PAY_SUCCESS",
  "blockHeight": 19384738
}

Refund Status Notification

Request Parameters (Refund Notification):

Field Name	Type	Maximum Length	Description
`refundId`	String	64	Refund ID
`orderId`	String	64	Original Order ID
`refundAmount`	String	64	Refund Amount
`currency`	String	16	Currency
`txHash`	String	64	Blockchain Transaction Hash (using camelCase)
`status`	String	16	Refund Status (consistent with other)
`blockHeight`	Long	-	Block Height

Request Example

{
  "refundId": "R202401010001",
  "orderId": "O202401010001",
  "refundAmount": "100.00",
  "currency": "USDT",
  "txHash": "0xabc123...def456",
  "status": "SUCCESS",
  "blockHeight": 19384800
}

Payout Status Notification

Request Parameters (Payout Notification):

Field Name	Type	Maximum Length	Description
`payoutId`	String	64	System Payout ID
`merchantOrderNo`	String	128	Merchant Business Order Number
`amount`	String	64	Payout Amount
`currency`	String	8	Payout Currency
`chain`	String	16	Chain Type
`txHash`	String	64	Blockchain Transaction Hash
`status`	String	16	Payout Status (consistent with other)

Request Example

{
  "payoutId": "PO202401010001",
  "merchantOrderNo": "PO202401010001",
  "amount": "1000.00",
  "currency": "USDT",
  "chain": "ETH",
  "txHash": "0xdef456...abc123",
  "status": "SUCCESS"
}

Merchant Response Requirements and Retry Mechanism

The merchant service must return an HTTP 200 status code to indicate successful receipt and processing of the notification.
A non-200 status code or timeout will be considered a failure, and the system will retry a certain number of times (the specific strategy is subject to the platform’s actual configuration).
It is recommended to return a unified response format:

{
  "code": "SUCCESS"
}

Important Requirements:

The notification processing logic on the merchant side must implement idempotency (for example, deduplication through orderId/refundId + status) to avoid duplicate processing of business operations caused by repeated notifications.

Before business processing, signature verification and parameter verification must be performed first, and all requests that fail verification should be rejected.

Best Practice Recommendations

Idempotency Control
1. Use bizNo to ensure idempotency for order creation: Requests with the same bizNo will return the same order information.
2. It is recommended to use UUID or a business-unique identifier as bizNo.
Order Status Polling
1. The “Query Order” interface can be polled from the frontend or merchant system based on business needs. Set reasonable polling intervals and maximum polling durations to avoid overly frequent requests.
Callback Notification Handling
1. Upon receiving order/refund status notifications, first perform signature verification and parameter validation before proceeding with business processing.
2. Implement idempotent logic to ensure that multiple notifications do not result in duplicate deductions or duplicate shipments.
Error Handling and Troubleshooting
1. Determine request success based on the code field. In case of failure, troubleshoot using msg prompts and business logs.
2. When troubleshooting with the platform, provide the corresponding traceId, request time range, and key business information (e.g., orderId/bizNo).
Security Recommendations
1. ApiKey/AppSecret should only be used on the server side and not exposed in frontend, mobile, or browser environments.
2. Configure IP whitelists to restrict access to trusted servers only.
3. Use HTTPS throughout to avoid plaintext transmission.
4. Regularly rotate keys and promptly update them in server configurations.

Frequently Asked Questions (FAQ) Examples

Q: What should I do if I receive a 1010 authentication failure message when creating an order? Please check:

Whether the request carries the correct X-Api-Key and X-App-Id in the Header;
Whether X-Timestamp is within the allowed time window (not expired);
Whether X-Nonce is different for each request;
Whether the signature X-Signature is generated according to the documentation requirements;
Whether the API Key has been enabled in the backend and is not expired;
Whether the current request IP is within the configured whitelist range.

Q: What should I do if I don’t receive callback notifications? Please check:

Confirm that the notification URL has been correctly configured in the merchant backend;
Check whether the merchant service can be accessed from the public network and is not blocked by a firewall;
Review server logs to confirm whether any requests arrived but returned non-200 status codes or timed out;
Confirm whether signature verification has been correctly handled (platforms that fail verification will log failures, which can be cross-checked with the platform using traceId);
Compare status updates using the order/refund query interface.

Q: How can I avoid duplicate processing of callback notifications? Please check:

Before processing, first check based on orderId/refundId + status whether this status has already been processed; if so, return success directly to maintain idempotency.

Q: In a multi-chain payment scenario, if a user transfers partial amounts to ETH and TRX addresses separately, how is the order considered successful? Please check:

It is recommended that the frontend only display and guide users to select one chain to complete payment. If supporting multiple cumulative payments is necessary:
Confirm with the platform whether amount accumulation across multiple chains/transactions on an order basis is allowed;
If allowed, establish business rules to consider the order successful once the cumulative amount reaches the expected total, and include transaction details in statements.

Getting started

Digital Wallet

Acquiring System

ISV Enablement Solution

Other Resources

API Doc

2026/05/08

Integration process

Environment Setup

Basic Environment

Authentication Security

IP Whitelist

Order Management

Create Order

Query Order

Query Statement

Refund Management

Create Refund

Query Refund

Payout Management

Create Payout

Query Payout

Status Notification (Webhook, with Signature)

Order Status Notification

Refund Status Notification

Payout Status Notification

Best Practice Recommendations

Frequently Asked Questions (FAQ) Examples

​2026/05/08

​Integration process

​Environment Setup

​Basic Environment

​Authentication Security

​IP Whitelist

​Order Management

​Create Order

​Query Order

​Query Statement

​Refund Management

​Create Refund

​Query Refund

​Payout Management

​Create Payout

​Query Payout

​Status Notification (Webhook, with Signature)

​Order Status Notification

​Refund Status Notification

​Payout Status Notification

​Best Practice Recommendations

​Frequently Asked Questions (FAQ) Examples

2026/05/08

Integration process

Environment Setup

Basic Environment

Authentication Security

IP Whitelist

Order Management

Create Order

Query Order

Query Statement

Refund Management

Create Refund

Query Refund

Payout Management

Create Payout

Query Payout

Status Notification (Webhook, with Signature)

Order Status Notification

Refund Status Notification

Payout Status Notification

Best Practice Recommendations

Frequently Asked Questions (FAQ) Examples