Crypto Pay-In
Overview
The Crypto Pay-In API collects on-chain transfers from payers. The merchant specifies currency and netWork in the order request. The platform assigns a deposit address inAddress to the order, the payer transfers the specified quantity to that address, and once the transfer is confirmed on-chain the platform notifies the merchant via callback.
Common request headers (including the mandatory Nonce), common body fields and the unified response envelope are described in Crypto Integration Overview.
Create Pay-In Order (orderDirectly)
The merchant specifies currency and netWork in the request. The platform requests a deposit address from the channel and returns inAddress directly.
Request path
Domain: Prefer unified host
openapi.toppayment.com(path unchanged); legacy crypto domain (global-digit-openapi.toppayment.com) remains available.
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/crypto/sandbox/pay/directlyPay |
| Production | https://openapi.toppayment.com/crypto/pay/orderDirectly |
Sandbox path difference
The sandbox direct-order path is /crypto/sandbox/pay/directlyPay (/crypto/sandbox/pay/transOrder is also accepted), which differs in name from the production /crypto/pay/orderDirectly. Request and response bodies are identical.
Request headers
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | Fixed value: application/json |
| Nonce | M | String(16-64) | Anti-replay random string, unique within 10 minutes, excluded from the signature |
Request body
| Field | Required | Type | Description |
|---|---|---|---|
| mchNo | M | String(32) | Merchant number In sandbox use the SD-prefixed sandbox merchant number |
| mchUserId | M | String(32) | Merchant-side user identifier Used to link the payer to your own system |
| payMoney | M | String | Collection quantity Numeric string with at most 6 decimal places Subject to the platform pre-order amount limits; out-of-range returns 0001Example: 10.5 |
| currency | M | String(16) | Coin Charset A-Z a-z 0-9 _, example: USDT |
| netWork | M | String(100) | Chain network Example: TRC20 |
| downNotifyUrl | M | String(255) | Asynchronous notification URL Must be a publicly reachable HTTP/HTTPS URL, see Callback |
| timestamp | M | String(13) | Request timestamp (13-digit milliseconds), within ±5 minutes |
| sign | M | String | Signature, see Signature |
| orderNum | O | String(64) | Merchant order number Generated by the platform when omitted. Must be unique per merchant; duplicates return 0001 |
| expiryPeriod | O | String | Order validity in minutes Range 1–9999, defaults to 1440 (24 hours) |
| orderVersion | O | String(20) | Order version marker agreed with the platform, normally not needed |
| name | O | String(64) | Payer name |
| O | String(64) | Payer email | |
| phone | O | String(32) | Payer phone |
| tenantCode | O | String(32) | Sub-tenant code, defaults to the default tenant |
| countryCode | O | String(16) | Country code, not needed for crypto |
A missing currency or netWork returns 0001; no available channel for the coin returns 0003.
Request example
Content-Type: application/json
Nonce: 2b7de401a5c96f83d0e1
{
"mchNo": "{{mchNo}}",
"mchUserId": "USER_10001",
"payMoney": "10.5",
"orderNum": "CRAPI1788506800931",
"currency": "USDT",
"netWork": "TRC20",
"downNotifyUrl": "https://example.com/notify/pay",
"expiryPeriod": "1440",
"timestamp": "1749451858772",
"sign": "replace with generated signature"
}
Response body
| Field | Required | Type | Description |
|---|---|---|---|
| success | M | Boolean | Whether the request succeeded |
| code | M | String | Response code 9999: success; otherwise see Exception Codes |
| msg | O | String | Response message, null on success |
| timeStamp | M | Number | Server response time (milliseconds) |
| data | M | Object | Response payload |
| orderNum | M | String | Merchant order number Platform-generated when omitted in the request |
| platOrderNum | M | String | Platform order number The key used for later inquiries and callbacks |
| payMoney | M | Number | Collection quantity |
| currency | M | String | Coin |
| netWork | M | String | Chain network |
| inAddress | M | String | Deposit address Instruct the payer to transfer payMoney of currency to this address |
Response example
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "CRAPI1788506800931",
"platOrderNum": "CR20260904152640642",
"payMoney": 10.500000,
"currency": "USDT",
"netWork": "TRC20",
"inAddress": "TP5wzCqNsJFNT83m1VXdF2Aj1ageFWgqW2"
}
}
Notes
The transferred quantity must match the order
The on-chain transfer must match payMoney exactly and must use the currency and netWork of the order. A mismatched quantity, wrong chain or wrong coin may prevent automatic crediting and require manual intervention.
- The deposit address is bound to the order. Never reuse an
inAddressfrom a previous order. - Orders expire after
expiryPeriod; expired orders return statusEXPIREDon inquiry. - Reusing the same
mchNo+orderNumreturns0001(The order already exists!); concurrent duplicate submissions return0004.
Next steps
- Order status and fees: Crypto Order Inquiry
- Payment result notification: Crypto Callback
