Transaction Endpoints

Query transaction details and status for payment orders.

Query Transaction Details

Transaction information is included in the order status response. Use the Query Payment Order Status endpoint to retrieve transaction details.

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

Parameter	Type	Required	Description
merchantOrderId	string	✅ Yes	Your merchant order ID
payOrderId	string	✅ Yes	HashNut platform order ID
accessSign	string	✅ Yes	Access signature from create order response

Response

Success Response (200 OK):

{
  "code": 0,
  "msg": "success",
  "data": {
    "merchantOrderId": "e30ff306-5552-497d-9083-fd6e943dfd73",
    "payOrderId": "01KBZ292SK2GKFK97916F5EC3B",
    "payTxId": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "confirmCount": "12",
    "state": 4,
    "chainCode": "erc20",
    "coinCode": "usdt",
    "amount": 0.01,
    "tokenAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "receiptAddress": "0x5678...",
    "createTime": "2024-01-01T00:00:00Z"
  }
}

Transaction Fields

Field	Type	Description
payTxId	string	Transaction hash on the blockchain (available after payment is sent)
confirmCount	string	Number of blockchain confirmations received
state	integer	Order/transaction state (see Order States)
chainCode	string	Chain code (e.g., "erc20", "bsc-erc20")
coinCode	string	Currency code (e.g., "usdt", "usdc")
amount	decimal	Transaction amount
tokenAddress	string	Token contract address
receiptAddress	string	Receiving address
createTime	string	Transaction creation timestamp (ISO format)

Transaction States

State	Code	Description
Unpaid	0	Order created, no transaction yet
Not Completed	1	Transaction initiated but not completed
Waiting for Confirmation	2	Transaction broadcast, awaiting confirmation
Confirming	3	Transaction confirmed, verifying payment
Success	4	Transaction confirmed and payment verified
Failed	-1	Transaction failed
Expired	-2	Order expired without transaction
Cancelled	-3	Order cancelled

Code Examples

JavaScript

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 tx = result.data;
  console.log('Transaction Hash:', tx.payTxId);
  console.log('Confirmations:', tx.confirmCount);
  console.log('State:', tx.state);
  
  // View transaction on blockchain explorer
  if (tx.payTxId && tx.chainCode === 'erc20') {
    const explorerUrl = `https://etherscan.io/tx/${tx.payTxId}`;
    console.log('View on Etherscan:', explorerUrl);
  }
}

Python

import requests

response = requests.post(
    'https://testnet.hashnut.io/api/v3.0.0/pay/queryPayOrderWithAccessSign',
    headers={'Content-Type': 'application/json'},
    json={
        'merchantOrderId': 'order-123',
        'payOrderId': '01KBZ292SK2GKFK97916F5EC3B',
        'accessSign': 'D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5'
    }
)

result = response.json()
if result['code'] == 0:
    tx = result['data']
    print(f"Transaction Hash: {tx['payTxId']}")
    print(f"Confirmations: {tx['confirmCount']}")
    print(f"State: {tx['state']}")
    
    # View transaction on blockchain explorer
    if tx.get('payTxId') and tx['chainCode'] == 'erc20':
        explorer_url = f"https://etherscan.io/tx/{tx['payTxId']}"
        print(f"View on Etherscan: {explorer_url}")

cURL

curl -X POST 'https://testnet.hashnut.io/api/v3.0.0/pay/queryPayOrderWithAccessSign' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantOrderId": "order-123",
    "payOrderId": "01KBZ292SK2GKFK97916F5EC3B",
    "accessSign": "D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5"
  }'

Viewing Transactions on Blockchain Explorers

Once you have the transaction hash (payTxId), you can view it on the appropriate blockchain explorer:

Chain	Explorer URL Pattern
Ethereum (erc20)	https://etherscan.io/tx/{payTxId}
BSC (bsc-erc20)	https://bscscan.com/tx/{payTxId}
Polygon (polygon-erc20)	https://polygonscan.com/tx/{payTxId}
TRON (tron-trc20)	https://tronscan.org/#/transaction/{payTxId}

Best Practices

1. Check Transaction Hash: Only process transactions that have a payTxId (transaction hash)
2. Verify Confirmations: Wait for sufficient confirmations before marking payment as complete
3. Monitor State: Track state changes from 2 (Waiting) → 3 (Confirming) → 4 (Success)
4. Handle Failures: Check for state -1 (Failed) and handle accordingly
5. Use Webhooks: Prefer webhooks over polling for real-time transaction updates

Related Endpoints

• Query Order Status: Get full order and transaction details
• Create Order: Create a new payment order
• Webhooks: Receive real-time transaction notifications

Next Steps

• Learn about Order States in detail
• Set up Webhooks for transaction notifications
• Explore Multi-Chain Support for different networks

---

Need help? Check the Order Endpoints for complete order management