API Document

# Callback Transaction Result

# Callback Interface Signature Verification

Purpose of Signature Verification

During API requests, there is a risk of data being tampered with by a middleman while being transmitted over the public network. To ensure the integrity and trustworthiness of the callback data, the platform supports and strongly recommends that merchants perform signature verification when receiving the callback.

Setup Method

Log in to the [Cashier Backend] → [Developer Center] → [Callback Address] → Add/Edit.

Signature Verification Steps

The signature verification logic is generally the same as the API request signature, with the key difference being that the data source is the received callback content.

1.Obtain the Signature

Retrieve the signature field from the HTTP request Header：

sign: {Platform-generated signature string}

2.Obtain the Callback Parameters

​ Store the JSON parameters from the callback Body in a Map (dictionary) structure in key-value form.

3.Add Public Parameters

​ Also retrieve the following fields from the Header and include them in the Map for signature verification:

  1. access_key
  • timestamp
  • nonce

4.Construct the String to Be Signed

​ Sort all the keys in the Map in ASCII order from smallest to largest, and concatenate them into the following format: plaintext

key1=value1&key2=value2&...&keyN=valueN

5.Perform Signature Calculation

  1. Use the secret_key bound to the merchant's backend to process the above string as follows:
    • Encrypt using the HMAC_SHA1 algorithm
    • Base64 encode the result to obtain the local sign value

6.Compare Signatures

Compare the locally generated sign with the sign provided in the Header by the platform:

  • ✅ If they match → Signature verification passes, and business logic can be processed
  • ❌ If they don't match → Reject processing and consider logging the event for troubleshooting

# Payment Callback

Interface Description

When a user completes a payment on the blockchain, the platform will automatically send a callback request (HTTP POST) to the merchant's system based on the order status. The callback information includes key fields such as payment status, amount, and blockchain transaction hash.

Callback Data Format (JSON)

{
  "currencyType": "USD",
  "orderActualAmount": "1",
  "orderId": "OCRYPPAID202307310902391690794159441DOCKER020000000400001108",
  "tradeHash": "0x806d5b3da29c8426a644e2ded85b865b37504dcdec4cfb9db13af5e962815528",
  "orderFee": "1",
  "orderStatus": "Completed",
  "chainType": "ETH",
  "externalOrderId": "402297358314559082",
  "addressTo": "0xe072c63c1e04f8c6f36133f6629f66778147d5d8",
  "orderAmount": "1",
  "orderTime": 1690794159000,
  "exchangeRate": "0.983",
  "orderStatusCode": 4,
  "orderPayTime": 1690794247000,
  "addressFrom": "0x0cbfd17ae9e1d6d881b2cade71277f48abf64d24",
  "tokenType": "USDT"
}

Callback Field Descriptions

Parameter Name Type Description
orderActualAmount String The actual payment amount (token amount)
orderAmount String The original order amount (token amount)
orderFee String The transaction fee
orderId String The platform order ID
externalOrderId String The merchant's order ID
orderTime int64 The order creation time (milliseconds timestamp)
orderPayTime int64 The order completion time
currencyType String Fiat currency type, e.g., USD, BRL
exchangeRate String The fiat currency exchange rate when the order was created
chainType String Blockchain type, e.g., ETH, TRON, BSC
tokenType String Token type, e.g., USDT, USDC, DAI
addressTo String Receiving address (platform's receiving address)
addressFrom String The user's payment address (blockchain sending address)
tradeHash String Blockchain transaction hash, used for checking the transaction status
orderStatusCode int64 Status code, enumerated values: 1, 2, 4, 8, 16. Refer to the order status code description below
orderStatus String Order status description

Order Status Code Description

Status Code Status Description Final Status Description
1 Pending Payment No The order has been created, but the user has not paid yet. No action required.
2 Blockchain Confirmation No The user clicked “Payment Complete,” and the system is checking the blockchain for confirmation. No action required.
4 Completed Yes Payment is successful, and the system will trigger a callback. The merchant should update balances or fulfill the order as per business logic.
8 Payment Mismatch Yes The user’s payment amount ≠ the amount due. The system will trigger a callback. It is recommended to credit the actual payment amount.
16 Payment Timeout Yes The user’s payment exceeded the time limit. The system will not trigger another callback. The merchant should handle manually if payment was received.
32 Unpaid (Address Released) Yes The user has not paid in time, and the address has been released. A new order will be generated if payment is made later.

📌 Manual Callback Description (Merchant Backend Operation)

Merchants can manually trigger a callback notification for specific orders at any time via the merchant backend.

Usage

  • Login to the merchant backend → Order Management → Actions;
  • Click [Manual Callback], and the platform will immediately send a callback to the notifyUrl of the order.

⚠️ Important Notes

  • It is recommended to only trigger a manual callback for orders that have reached the "final status":
    • That is, orderStatusCode = 4 (Completed), 8 (Payment Mismatch), 16 (Timeout), etc.;
  • Do not trigger a callback for non-final status orders (such as status 1 Pending Payment, 2 Confirming):
      • The order may still reach a final status, and the platform will automatically trigger a callback when the status changes;
      • If the merchant processes an incomplete order repeatedly, it may lead to accounting errors or data duplication.

💡 Merchant Suggestions

  • Ensure to implement idempotent handling logic on the callback receiving end (only process a callback once for the same order);
  • For callbacks that were not received due to exceptions, check the signature, header parameters, and network connectivity, and consider triggering a manual callback.

# Payment Callback

Interface Description

When the status of a blockchain-based payment order initiated by the merchant changes (such as payment success, failure, rejection, etc.), the platform will automatically send a callback notification to the merchant-configured notifyUrl.

Callback Data Format (JSON)

{
  "orderAmount": "1",
  "orderTime": 1690794160000,
  "orderId": "OCRYPDRAW202307310902401690794160841DOCKER020000000200001109",
  "orderStatusCode": 2,
  "tradeHash": "0xe9d043c9cbdb96ed7a71c5a0923baabe9e23316b3f1b0a01975bcd6d69b41fa3",
  "orderFee": "0.01",
  "orderStatus": "Completed",
  "orderPayTime": 1690794182000,
  "chainType": "ETH",
  "externalOrderId": "622257420681202921",
  "tokenType": "USDT",
  "addressTo": "0xa8666442fA7583F783a169CC9F5449ec660295E8"
}

Callback Field Descriptions

Parameter Name Type Description
orderId String Platform order ID
externalOrderId String Merchant order ID
orderAmount String Original payment amount (in token units)
orderFee String Transaction fee (platform's fee)
orderTime int64 Order creation time (milliseconds timestamp)
orderPayTime int64 Actual payment completion time
chainType String Blockchain type, e.g., ETH, TRON, BSC
tokenType String Cryptocurrency type, e.g., USDT, USDC, DAI
tradeHash String Blockchain transaction hash, used to query transaction status on the blockchain
addressTo String Recipient's address
orderStatus String Order status description, e.g., Completed
orderStatusCode int64 Order status code, see below for status code definitions

orderStatusCode Status Code Definitions

Status Code Description Final Status Explanation
1 Accepted No The platform has received the payment request but has not processed it on the blockchain yet.
2 Completed Yes Payment successful, transaction confirmed on the blockchain.
4 Payment Failed Yes Payment failed (e.g., insufficient fees, blockchain issues).
8 Pending Approval No Manual review is required due to risk control or permission configuration.
16 Payment Rejected Yes Review failed, order terminated.

# Callback Response

Description

  • All callbacks include a signature field. It is recommended that merchants validate the callback to ensure the integrity of the callback data.
  • After receiving and processing the callback data, merchants must respond to the gateway with the following JSON format:

Example Response (Success)

{
  "code": 200,
  "success": true
}

Callback Retries Mechanism (Important) 🔥

To ensure stable delivery and business consistency of the callback notifications, the platform has designed a retry strategy. If the merchant system fails to respond to the callback (e.g., network timeout, returns a non-200 status code, etc.), the system will retry according to the following rules:

Callback Retry Schedule (4 attempts total):

Attempt No. Interval (approx.) Description
1st Attempt About 2 minutes First retry after initial failure
2nd Attempt About 2 minutes Second retry after first failure
3rd Attempt About 11 minutes Third retry after second failure
4th Attempt About 2 minutes Final retry after third failure

Note: The intervals above represent internal scheduling intervals. The "callback time" recorded in the merchant's backend includes the merchant's processing/response time, so there may be a slight discrepancy (about 1 minute) between the displayed and actual push times.

Practical Reminders

  • When there is a large volume of orders online, callbacks may experience queue delays, so please ensure the server can handle high concurrency.
  • Each callback is an idempotent operation, and merchants should support idempotent checks.
  • After 4 failed retry attempts, the system will stop retrying automatically, and it is recommended to manually trigger the callback via the backend.

Callback Response Parameters

Param Type Required Description
code int ✅ Status code; 200 for success
success boolean ✅ Whether the response was successful

# Callback Notification URL Configuration

Two types of notification address configurations are supported:

  1. [Merchant Backend] Configure a Unified Callback Address
  • This can be configured in the "Merchant Backend" → "Developer Center."
  • Suitable for handling callbacks with common logic across most orders.

img

  1. Order-level Manual Specification of Callback URL (notifyUrl)
  • The notifyUrl field can be passed when creating an order.
  • If the order specifies the notifyUrl parameter, the system will use that address as the only callback notification target.

Priority of Address Configuration

The notifyUrl in the order takes precedence over the unified callback address configured in the system.

Priority of Response Status Code

The platform uses the HTTP response status code (status_code) as the only criterion to determine whether the callback was successful.

Specific Rules:

  • ✅ As long as the merchant system returns HTTP 200, the platform will consider the callback as successful.
    • In this case, even if the returned content is not { "code": 200, "success": true }, it will be ignored.
  • ❌ If the response status_code ≠ 200 (e.g., 400/500) or there is no response, the callback will be considered failed, and the platform will automatically retry the push.

← 1、Create Payment Request →