Skip to main content

Order Endpoints

Create and manage payment orders through the HashNut API.

Create Payment Order​

Creates a new payment order and returns payment details including a payment URL.

Endpoint: POST /api/v3.0.0/pay/createPayOrderOnSplitWalletWithApiKey

Request​

Headers:

hashnut-request-uuid: <uuid>
hashnut-request-timestamp: <timestamp>
hashnut-request-sign: <signature>
Content-Type: application/json

Body:

{
  "accessKeyId": "string",
  "merchantOrderId": "string",
  "chainCode": "string",
  "coinCode": "string",
  "amount": 0.01,
  "callBackUrl": "string",
  "frontendCallbackUrl": "string",
  "receiptAddress": "string",
  "splitterAddress": "string"
}

Request Parameters​

ParameterTypeRequiredDescription
accessKeyIdstring✅ YesYour merchant access key ID
merchantOrderIdstring✅ YesUnique merchant order ID (max 255 characters, must be unique per merchant)
chainCodestring✅ YesChain code. Supported values: "erc20", "bsc-erc20", "polygon-erc20", "tron-trc20"
coinCodestring✅ YesCurrency code (e.g., "usdt", "usdc", "MockUSDT") - case-sensitive
amountdecimal✅ YesPayment amount in base unit (e.g., 0.01 for 0.01 USDT). Minimum: 0.01. Round to 2 decimal places.
callBackUrlstring⚠️ OptionalBackend webhook URL for payment status updates
frontendCallbackUrlstring⚠️ OptionalFrontend redirect URL after payment completion
receiptAddressstring⚠️ OptionalCustom merchant receiving address. Must match format: EVM (0x...) or TRON (T...). If not provided, uses default from account.
splitterAddressstring⚠️ OptionalSplitter contract address (smart contract for receiving payments). Must be EVM format (0x...).

Response​

Success Response (200 OK):

{
  "code": 0,
  "msg": "success",
  "data": {
    "payOrderId": "01KBZ292SK2GKFK97916F5EC3B",
    "accessSign": "D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5",
    "merchantOrderId": "e30ff306-5552-497d-9083-fd6e943dfd73"
  }
}

Response Fields​

FieldTypeDescription
payOrderIdstringHashNut platform order ID (unique identifier)
accessSignstringAccess signature for querying order status
merchantOrderIdstringEcho of merchant order ID

Payment URL Construction​

After receiving the response, construct the payment URL:

https://testnet.hashnut.io/pay?accessSign={accessSign}&merchantOrderId={merchantOrderId}&payOrderId={payOrderId}&chainCode={chainCode}

Example:

https://testnet.hashnut.io/pay?accessSign=D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5&merchantOrderId=e30ff306-5552-497d-9083-fd6e943dfd73&payOrderId=01KBZ292SK2GKFK97916F5EC3B&chainCode=erc20

Error Responses​

Invalid Signature (401):

{
  "code": -2,
  "msg": "Invalid signature or credentials",
  "data": null
}

Invalid Parameters (400):

{
  "code": -2,
  "msg": "Invalid parameters",
  "data": null
}

Common Errors:

  • -2: Authentication/signature error, invalid credentials, or missing required fields
  • Other codes: See Error Codes

Code Examples​

const response = await fetch(
  'https://testnet.hashnut.io/api/v3.0.0/pay/createPayOrderOnSplitWalletWithApiKey',
  {
    method: 'POST',
    headers: {
      'hashnut-request-uuid': uuid,
      'hashnut-request-timestamp': timestamp,
      'hashnut-request-sign': signature,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      accessKeyId: 'YOUR_ACCESS_KEY_ID',
      merchantOrderId: `order-${Date.now()}`,
      chainCode: 'erc20',
      coinCode: 'usdt',
      amount: 0.01,
      callBackUrl: 'https://your-site.com/webhook',
      frontendCallbackUrl: 'https://your-site.com/payment/success'
    })
  }
);

const result = await response.json();
if (result.code === 0) {
  const paymentUrl = `https://testnet.hashnut.io/pay?accessSign=${result.data.accessSign}&merchantOrderId=${result.data.merchantOrderId}&payOrderId=${result.data.payOrderId}&chainCode=erc20`;
  console.log('Payment URL:', paymentUrl);
}

Query Payment Order Status​

Queries the current status of a payment order using the access sign.

Endpoint: POST /api/v3.0.0/pay/queryPayOrderWithAccessSign

Request​

Headers:

Content-Type: application/json

Note: This endpoint does NOT require signature authentication (uses accessSign instead).

Body:

{
  "merchantOrderId": "string",
  "payOrderId": "string",
  "accessSign": "string"
}

Request Parameters​

ParameterTypeRequiredDescription
merchantOrderIdstring✅ YesYour merchant order ID
payOrderIdstring✅ YesHashNut platform order ID
accessSignstring✅ YesAccess signature from create order response

Response​

Success Response (200 OK):

{
  "code": 0,
  "msg": "success",
  "data": {
    "merchantAddress": "0x1234...",
    "chain": "Ethereum",
    "chainCode": "erc20",
    "coinCode": "usdt",
    "createChannel": 0,
    "accessChannel": 0,
    "merchantOrderId": "e30ff306-5552-497d-9083-fd6e943dfd73",
    "payOrderId": "01KBZ292SK2GKFK97916F5EC3B",
    "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "receiptAddress": "0x5678...",
    "amount": 0.01,
    "state": 4,
    "accessSign": "D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5",
    "payTxId": "0xabcdef1234567890...",
    "confirmCount": "12",
    "walletConnectEnable": true,
    "bridgeServerAddress": "https://bridge.hashnut.io",
    "eip712ChainId": "1",
    "chainId": "1",
    "callBackUrl": "https://merchant.com/api/payment/webhook",
    "createTime": "2024-01-01T00:00:00Z",
    "rate": 1.0,
    "obtainAmount": 0.01,
    "platformFee": 0
  }
}

Response Fields​

FieldTypeDescription
merchantAddressstringMerchant wallet address
chainstringChain name (e.g., "Ethereum", "BSC")
chainCodestringChain code (e.g., "erc20")
coinCodestringCurrency code (e.g., "usdt")
merchantOrderIdstringMerchant order ID
payOrderIdstringHashNut platform order ID
tokenAddressstringToken contract address
receiptAddressstringReceiving address
amountdecimalPayment amount
stateintegerOrder state (see Order States)
accessSignstringAccess signature
payTxIdstringTransaction hash (if paid)
confirmCountstringConfirmation count
walletConnectEnablebooleanWhether WalletConnect is enabled
bridgeServerAddressstringBridge server address
eip712ChainIdstringEIP-712 chain ID
chainIdstringChain ID
callBackUrlstringWebhook callback URL
createTimestringCreation timestamp (ISO format)
ratedecimalExchange rate (if applicable)
obtainAmountdecimalAmount obtained by merchant
platformFeedecimalPlatform fee

Order States​

StateCodeDescription
Unpaid0Order created, awaiting payment
Not Completed1Payment initiated but not completed
Waiting for Confirmation2Transaction broadcast, awaiting confirmation
Confirming3Transaction confirmed, verifying payment
Success4Payment complete and verified
Failed-1Payment transaction failed
Expired-2Order expired without payment
Cancelled-3Order cancelled by merchant

See Order States for detailed information.

Code Examples​

const response = await fetch(
  'https://testnet.hashnut.io/api/v3.0.0/pay/queryPayOrderWithAccessSign',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      merchantOrderId: 'order-123',
      payOrderId: '01KBZ292SK2GKFK97916F5EC3B',
      accessSign: 'D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5'
    })
  }
);

const result = await response.json();
if (result.code === 0) {
  const order = result.data;
  console.log('Order State:', order.state);
  console.log('Amount:', order.amount);
  if (order.state === 4) {
    console.log('Payment successful!');
  }
}

Best Practices​

  1. Always Query After Webhook: Even after receiving a webhook, query the order status to get the latest state
  2. Handle All States: Implement handling for all order states, especially terminal states (Success, Failed, Expired, Cancelled)
  3. Polling: If not using webhooks, poll order status regularly (but not too frequently)
  4. Error Handling: Always check response.code === 0 before processing data
  5. Idempotency: Use merchantOrderId to ensure order uniqueness and prevent duplicates

Next Steps​

Ready to create orders? Check out Quick Start →