Create Order
Create a new payment order. This endpoint uses header-based HMAC signing.
Endpoint
POST /v4.0.0/pay/orders/apiRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
accessKeyId | string | Yes | Your merchant Access Key ID |
merchantOrderId | string | Yes | Your unique order identifier (max 64 chars) |
chainCode | string | Yes | Token standard code (e.g., erc20, trc20, bep20, polygon-erc20) |
coinCode | string | Yes | Token code (e.g., usdt, usdc) |
amount | string | Yes | Payment amount as a decimal string (e.g., "10.50") |
splitterAddress | string | Yes | Your split wallet contract address |
subject | string | No | Order subject / description (max 256 chars) |
expireDuration | integer | No | Expiration time in seconds (default: 3600) |
callbackURL | string | No | Frontend redirect URL after payment (see Notifications) |
notifyURL | string | No | Backend webhook URL for order state updates |
metadata | string | No | Arbitrary metadata string (max 1024 chars, returned in notifications) |
WARNING
callbackURL is the frontend redirect URL shown to the customer after payment. For backend notifications, use notifyURL. See Notify URL vs Callback URL for details.
Example Request
json
{
"accessKeyId": "ak_test_abc123",
"merchantOrderId": "ORDER-20260621-001",
"chainCode": "erc20",
"coinCode": "usdt",
"amount": "10.50",
"splitterAddress": "0x1234567890abcdef1234567890abcdef12345678",
"subject": "Premium Subscription - 1 Month",
"expireDuration": 3600,
"callbackURL": "https://yoursite.com/payment-result",
"notifyURL": "https://yoursite.com/api/notify"
}Example Response
json
{
"code": 0,
"msg": "success",
"data": {
"payOrderId": "PO202606210001",
"merchantOrderId": "ORDER-20260621-001",
"receiptAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
"chainCode": "erc20",
"coinCode": "usdt",
"amount": "10.50",
"state": 0,
"expireTime": "2026-06-21T11:00:00Z"
}
}Response Fields
| Field | Type | Description |
|---|---|---|
code | integer | 0 for success, non-zero for error |
msg | string | Human-readable message |
data.payOrderId | string | HashNut-generated order ID |
data.merchantOrderId | string | Your original order ID |
data.receiptAddress | string | Blockchain address for the customer to pay to |
data.chainCode | string | Token standard code |
data.coinCode | string | Token code |
data.amount | string | Payment amount |
data.state | integer | Order state (0 = INIT). See Order States |
data.expireTime | string | ISO 8601 expiration timestamp |
TIP
Store both payOrderId and merchantOrderId on your side. Use merchantOrderId to correlate HashNut orders with your internal records.
Error Codes
| Code | Description |
|---|---|
0 | Success |
1001 | Invalid parameters |
1002 | Authentication failed |
1003 | Duplicate merchantOrderId |
1004 | No available receipt address |
1005 | Unsupported chain or coin |