Crypto Integration Overview

Overview

The Crypto (digital currency) Open API shares the same signature rules and unified response envelope as the fiat Open API, but the path prefix and some fields differ (recommended to share the unified host with fiat):

• The path prefix is always /crypto (fiat uses /{countryCode}, e.g. /ph, /id).
• Requests must carry the anti-replay header Nonce (not required by fiat endpoints).
• Amounts are on-chain quantities rather than fiat amounts, with at most 6 decimal places. Balances and callback amounts are returned with 8 decimal places.
• A transaction is identified by currency + netWork (coin + chain network), for example USDT + TRC20.

Field name case sensitivity

The API field is netWork (capital W), not network. Use the exact spelling in requests, responses, and signature concatenation.

Environments and domains

Crypto is not separated by country; the path prefix is always /crypto.

Type	Domain	Notes
Unified domain (recommended)	openapi.toppayment.com	Same host as fiat; path remains /crypto/...
Legacy crypto domain (compatible)	global-digit-openapi.toppayment.com	Remains available

Path templates ({host} per the table above):

Sandbox: https://{host}/crypto/sandbox/...
Production: https://{host}/crypto/...

Examples (recommended):

Sandbox: https://openapi.toppayment.com/crypto/sandbox/...
Production: https://openapi.toppayment.com/crypto/...

Endpoint list

Scenario	Sandbox URL	Production URL	Reference
Pay-in — cashier pre-order	https://openapi.toppayment.com/crypto/sandbox/pay/prePay	https://openapi.toppayment.com/crypto/pay/prePay	Crypto Pay-In
Pay-in — direct API order	https://openapi.toppayment.com/crypto/sandbox/pay/directlyPay	https://openapi.toppayment.com/crypto/pay/orderDirectly	Crypto Pay-In
Pay-in — order inquiry	https://openapi.toppayment.com/crypto/sandbox/pay/query	https://openapi.toppayment.com/crypto/pay/query	Order Inquiry
Pay-out — create order	https://openapi.toppayment.com/crypto/sandbox/disbursement/cash	https://openapi.toppayment.com/crypto/disbursement/cash	Crypto Pay-Out
Pay-out — order inquiry	https://openapi.toppayment.com/crypto/sandbox/disbursement/query	https://openapi.toppayment.com/crypto/disbursement/query	Order Inquiry
Balance inquiry	https://openapi.toppayment.com/crypto/sandbox/balance/v1	https://openapi.toppayment.com/crypto/balance/v1	Balance Inquiry
Callback notification	Provided by merchant via downNotifyUrl	Provided by merchant via downNotifyUrl	Callback

Sandbox path difference

The production direct-order path is /crypto/pay/orderDirectly, while the sandbox path is /crypto/sandbox/pay/directlyPay (/crypto/sandbox/pay/transOrder is also accepted). The request and response bodies are identical.

Common request headers

All crypto endpoints are POST with a JSON body.

Field	Required	Type	Description
Content-Type	M	String	Fixed value: application/json
Nonce	M	String(16-64)	Anti-replay random string Charset A-Z a-z 0-9 _ -, length 16–64 Must be unique per mchNo within a 10-minute window; reuse returns 0001 Excluded from sign calculation Not validated in sandbox, but sending it is recommended

Common request body fields

The fields below are shared by all endpoints and are not repeated in each reference page.

Field	Required	Type	Description
mchNo	M	String(32)	Merchant number In sandbox, use the sandbox merchant number prefixed with SD
timestamp	M	String(13)	Request timestamp (13-digit milliseconds) Must be within ±5 minutes of server time, otherwise 0001 is returned
sign	M	String	Signature, see Signature
tenantCode	O	String(32)	Sub-tenant code Defaults to the merchant's default tenant
countryCode	O	String(16)	Country code, not needed for crypto

Unified response envelope

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; on failure formatted as [0002]signature verification failed!
timeStamp	M	Number	Server response time (milliseconds)
data	O	Object	Business payload, see each endpoint

Supported coins and networks

Available currency / netWork combinations are enabled per merchant on the platform side. Refer to your merchant portal or account manager for the authoritative list. Common values:

currency	Common netWork
USDT	TRC20, ERC20
USDC	TRC20, ERC20
TRX	TRC20
ETH	ERC20
BTC	BTC

Cashier method notation

In the cashier page, a payment method is expressed as {currency}-{netWork}, e.g. USDT-TRC20. The underscore form USDT_TRC20 is also accepted.

Sandbox notes

• The merchant number must be prefixed with SD (production 123456 → sandbox SD123456), and the sandbox merchant public key must be uploaded in the merchant portal.
• Sandbox never calls a real blockchain channel. Pay-in deposit addresses are mocked as SANDBOX_{platOrderNum}.
• Sandbox fees are always calculated at 1%.
• Sending money = 20000000 on a sandbox pay-out reliably triggers insufficient balance (1002), useful for testing failure branches.
• Sandbox balance inquiry returns a fixed balance of 2000000 and uses a different response shape from production, see Balance Inquiry.

References

• Signature
• Exception Codes
• Callback