​

2026/03/17

​

Integration process

​

Environment Setup

1. 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).
2. 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.
3. Integrate Core APIs
   1. Order Management: Create Order, Query Order, Query Reconciliation Statement.
   2. Refund Management: Create Refund, Query Refund.
4. Integrate Callback Notifications (Webhook)
   1. Configure Order/Refund 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
5. 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://acquiring.dev.rdezlink.tech
  • Production environment: Use the address provided by operations before go-live (example: https://acquiring.xxx.com)
• 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

1. 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)
2. Use AppSecret as the key to perform HMAC-SHA256 on signPayload; output the result as hexadecimal or Base64, which becomes X-Signature.
3. The platform server will verify the signature using the same rules:

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

​

IP Whitelist

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

• 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.

{
  "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).

​

Order Management

​

Create Order

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

{
  "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"
  },
  "notifyUrl": "https://merchant.example.com/callback/order",
  "riskInfo": {
    "ip": "192.168.1.100",
    "deviceId": "device123"
  }
}

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.

{
  "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

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

{
  "orderId": "O202401010001"
}

{
  "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

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

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

{
  "code": "0000",
  "msg": "success",
  "data": {
    "total": 100,
    "orderList": [
      {
        "orderId": "O202401010001",
        "bizNo": "BIZ202401010001",
        "userId": "U001",
        "expectedAmount": "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

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

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

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

​

Query Refund

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

{
  "refundId": "R202401010001"
}

{
  "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"
}

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

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

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

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

• 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

1. 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.
2. 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.
3. 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.
4. 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).
5. 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

• 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.

• 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.

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

• 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.