Skip to main content

Crypto Pay-In

TOPPAY TeamAbout 3 min

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.

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/crypto/sandbox/pay/directlyPay
Productionhttps://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

FieldRequiredTypeDescription
Content-TypeMStringFixed value: application/json
NonceMString(16-64)Anti-replay random string, unique within 10 minutes, excluded from the signature

Request body

FieldRequiredTypeDescription
mchNoMString(32)Merchant number
In sandbox use the SD-prefixed sandbox merchant number
mchUserIdMString(32)Merchant-side user identifier
Used to link the payer to your own system
payMoneyMStringCollection quantity
Numeric string with at most 6 decimal places
Subject to the platform pre-order amount limits; out-of-range returns 0001
Example: 10.5
currencyMString(16)Coin
Charset A-Z a-z 0-9 _, example: USDT
netWorkMString(100)Chain network
Example: TRC20
downNotifyUrlMString(255)Asynchronous notification URL
Must be a publicly reachable HTTP/HTTPS URL, see Callback
timestampMString(13)Request timestamp (13-digit milliseconds), within ±5 minutes
signMStringSignature, see Signature
orderNumOString(64)Merchant order number
Generated by the platform when omitted. Must be unique per merchant; duplicates return 0001
expiryPeriodOStringOrder validity in minutes
Range 1–9999, defaults to 1440 (24 hours)
orderVersionOString(20)Order version marker agreed with the platform, normally not needed
nameOString(64)Payer name
emailOString(64)Payer email
phoneOString(32)Payer phone
tenantCodeOString(32)Sub-tenant code, defaults to the default tenant
countryCodeOString(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

Response body

FieldRequiredTypeDescription
successMBooleanWhether the request succeeded
codeMStringResponse code
9999: success; otherwise see Exception Codes
msgOStringResponse message, null on success
timeStampMNumberServer response time (milliseconds)
dataMObjectResponse payload
orderNumMStringMerchant order number
Platform-generated when omitted in the request
platOrderNumMStringPlatform order number
The key used for later inquiries and callbacks
payMoneyMNumberCollection quantity
currencyMStringCoin
netWorkMStringChain network
inAddressMStringDeposit 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 inAddress from a previous order.
  • Orders expire after expiryPeriod; expired orders return status EXPIRED on inquiry.
  • Reusing the same mchNo + orderNum returns 0001 (The order already exists!); concurrent duplicate submissions return 0004.

Next steps