01. Introduction
Welcome to the CoinPayUSDT Merchant API! Our platform provides server-to-server gateway interfaces that allow your application to seamlessly accept deposits (payins) and dispatch payouts (withdrawals) using stablecoins on both TRC20 (Tron) and BEP20 (Binance Smart Chain) networks.
All request payloads must be encoded in JSON format, and the API responds with structured JSON representations. By default, API communication runs on standard secure TLS, enforcing strict origin checks and signature authentication.
Production Gateway URL
https://api.coinpayusdt.com/api/merchant
02. Authentication
To secure your server-to-server communication, CoinPayUSDT enforces a strict HMAC-MD5 digital signature authentication protocol. Every request sent to the API must include the following headers:
| Header | Type | Description |
|---|---|---|
| X-Api-Key | String | Your unique Merchant API Key, available in your dashboard. |
| X-Timestamp | String | The current Unix millisecond timestamp (e.g. 1680000000000). Requests with a drift greater than ±5 minutes will be rejected. |
| X-Signature | String | The computed MD5 hex signature validating payload integrity. See below for the algorithm. |
03. Signature Calculation
To ensure requests cannot be tampered with in transit, you must compute the X-Signature header value for every POST request using your private API secret key:
HMAC Signature Steps:
- Extract all request parameters from your request body JSON as a flat key-value object.
- Remove any keys with empty,
null, orundefinedvalues. - Sort the remaining keys lexicographically (ASCII ascending order).
- Join key-value pairs formatted as
key=value, separated by an&sign. - Append
×tamp={X-Timestamp value}and&key={your_api_secret_key}to the string. - Calculate the MD5 hash of the resulting string and format it as a lowercase hex string.
04. Payin API (Deposit)
Use this endpoint to request a new deposit order. The API returns a checkout URL where the customer is redirected to make a secure payment, as well as a temporary deposit address.
Creates a deposit order and registers the transaction.
Request Parameters (JSON Body)
| Field | Type | Required | Description |
|---|---|---|---|
| merchantOrderNo | String | Yes | Unique transaction ID from your system (1-64 characters). |
| coinType | Enum | Yes | USDT_TRC20 or USDT_BEP20 |
| amount | String | Conditional | USDT amount to pay (string, e.g. "100.00"). Required if not using local currency. |
| localAmount | Number | Conditional | Amount in local currency. Must be paired with currency. |
| currency | Enum | Conditional | Local currency code: CNY, INR, USD, EUR. |
| notifyUrl | String | No | Webhook URL to notify when order status changes. Overrides portal configuration. |
Queries the status of a specific deposit order by your merchant order number.
Request Parameters (JSON Body)
| Field | Type | Required | Description |
|---|---|---|---|
| merchantOrderNo | String | Yes | The merchant order number associated with the query. |
05. Payout API (Withdrawal)
Use this API to trigger automated payouts (withdrawals) from your merchant balance to your user's blockchain address. CoinPayUSDT executes payouts instantly, deducts funds, and processes network dispatches in real-time.
Creates a new payout transaction, freezing funds and dispatching blockchain transactions.
Request Parameters (JSON Body)
| Field | Type | Required | Description |
|---|---|---|---|
| merchantOrderNo | String | Yes | Unique payout transaction number generated by you. |
| amount | String | Yes | USDT amount to pay out (numeric string with up to 2 decimal places). |
| coinType | Enum | Yes | USDT_TRC20 or USDT_BEP20 |
| walletAddress | String | Yes | The destination USDT blockchain wallet address. |
| notifyUrl | String | No | Callback target to report payout settlement. |
Retrieves the real-time status of a payout request.
Request Parameters (JSON Body)
| Field | Type | Required | Description |
|---|---|---|---|
| merchantOrderNo | String | Yes | Your unique transaction identifier. |
06. Webhooks (Callbacks)
To keep your system informed of payment and settlement events, CoinPayUSDT dispatches real-time webhooks to your registered notifyUrl as JSON POST requests.
Strict Webhook Acknowledgment
Your endpoint must respond within 10 seconds with HTTP status code 200 OK containing the literal string "success" anywhere in the body. If your server returns anything else (or times out), CoinPayUSDT will retry the webhook up to 5 times (at 30s, 2m, 5m, 10m intervals).
Webhook Body Parameters
| Key | Type | Description |
|---|---|---|
| merchantOrderNo | String | Your original transaction order number. |
| internalOrderNo | String | The gateway's generated unique identifier. |
| orderStatus | String | "1" represents Success / Settled. "2" represents Failure / Expired. |
| amount | String | The requested transaction amount in USDT. |
| coinType | String | The stablecoin asset standard (USDT_TRC20 / USDT_BEP20). |
| coinAmount | String | The actual amount detected on-chain (may vary slightly for over/underpayments). |
| timestamp | Number | Unix millisecond timestamp of notification dispatch. |
curl -X POST https://api.coinpayusdt.com/api/merchant/payin \
-H "X-Api-Key: cp_live_84f93a7d2bc..." \
-H "X-Timestamp: 1680000000000" \
-H "X-Signature: c811b7d519b52a160..." \
-H "Content-Type: application/json" \
-d '{"merchantOrderNo": "order_123", "amount": "100.00", "coinType": "USDT_TRC20"}'