Payment Flow

Understanding the complete payment flow from order creation to fund withdrawal is essential for building reliable integrations.

Complete Payment Lifecycle

Detailed Payment Flow

Step-by-Step Sequence

Order States

State Transitions

State Descriptions

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

Payment Flow Phases

Phase 1: Order Creation

Process:

1. Merchant sends order creation request
2. API validates request and credentials
3. Smart contract assigns receipt address from pool
4. Order created with unique payOrderId
5. Payment URL generated with access signature
6. Response returned to merchant

Key Data:

• payOrderId: Unique platform order ID
• accessSign: Signature for querying order status
• receiptAddress: Address customer will pay to
• paymentUrl: Complete payment URL

Phase 2: Customer Payment

Customer Experience:

1. Customer clicks payment link
2. Payment page displays order details
3. Customer connects wallet (MetaMask, TronLink, etc.)
4. Customer reviews payment amount and details
5. Customer approves transaction in wallet
6. Transaction broadcast to blockchain

Phase 3: Payment Confirmation

Confirmation Process:

1. Transaction Broadcast (State: 1): Transaction sent to network
2. Waiting for Confirmation (State: 2): Waiting for block inclusion
3. Block Confirmed (State: 3): Transaction included in block
4. Payment Verification:
   • Verify amount matches order
   • Verify receipt address is correct
   • Verify token/currency is correct
   • Verify sufficient confirmations
5. Success (State: 4): Payment verified and complete

Confirmation Requirements:

• Ethereum: 12 confirmations (configurable)
• Polygon: 3 confirmations (configurable)
• BSC: 3 confirmations (configurable)
• TRON: 19 confirmations (configurable)

Phase 4: Notification

Notification Types:

1. Webhook (callBackUrl): Backend notification

   • POST request with payment status
   • Includes order details and transaction hash
   • Requires signature verification

2. Frontend Redirect (frontendCallbackUrl): Customer redirect

   • Redirect after payment completion
   • Includes order parameters in URL
   • Customer sees success page

Phase 5: Fund Management

Fund Management Steps:

1. Aggregate: Collect funds from receipt wallets to main contract
2. Withdraw: Transfer funds from contract to merchant wallet
3. Fee Deduction: Platform fees transparently calculated and deducted

Payment URL Structure

URL Format

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

URL Parameters

Parameter	Description	Required
accessSign	Signature for querying order status	✅ Yes
merchantOrderId	Merchant's order identifier	✅ Yes
payOrderId	HashNut platform order ID	✅ Yes
chainCode	Chain code (e.g., "erc20")	✅ Yes

URL Security

• Access Sign: Prevents unauthorized order access
• Expiration: Payment links expire after configured time
• One-Time Use: Links are validated on each access
• Signature Verification: All parameters verified server-side

Webhook Flow

Webhook Delivery

Webhook Payload

{
  "payOrderId": "01KBZ292SK2GKFK97916F5EC3B",
  "merchantOrderId": "order-123",
  "accessSign": "D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5",
  "state": 4
}

Webhook Retry Logic

• Retry Attempts: 3 retries with exponential backoff
• Retry Intervals: 1s, 5s, 30s
• Timeout: 30 seconds per attempt
• Success Response: Must return 200 OK with body "success"

Error Handling

Payment Errors

Common Errors:

• Insufficient Balance: Customer doesn't have enough tokens
• Wrong Network: Customer connected to wrong blockchain
• Amount Mismatch: Payment amount doesn't match order
• Address Mismatch: Payment sent to wrong address
• Transaction Rejected: Customer rejected transaction in wallet

Best Practices

For Merchants

1. Always Process Webhooks:

   • Query order status after receiving webhook
   • Handle idempotency (duplicate webhooks)
   • Return success response promptly

2. Monitor Order States:

   • Track order state transitions
   • Handle all terminal states (Success, Failed, Expired, Cancelled)
   • Implement retry logic for failed payments

3. Fund Management:

   • Aggregate funds regularly (not after every payment)
   • Set minimum aggregation amounts to optimize gas
   • Monitor contract balances

4. Error Handling:

   • Provide clear error messages to customers
   • Implement retry mechanisms
   • Log all payment attempts

For Customers

1. Verify Payment Details:

   • Check payment amount before approving
   • Verify recipient address
   • Confirm network/chain

2. Transaction Confirmation:

   • Wait for transaction confirmation
   • Save transaction hash
   • Contact merchant if issues

Next Steps

• Learn about Order Management
• Understand Webhook Integration
• Explore Fund Management

---

Ready to integrate? Check out Quick Start →