Understanding the Crypto Checkout Flow

Understanding the cryptocurrency payment flow is essential for building a reliable integration. This guide walks through each stage from invoice creation to final confirmation.

Payment Lifecycle Overview

┌─────────────┐    ┌──────────────┐    ┌─────────────┐    ┌───────────┐

│   Create    │───▶│   Customer   │───▶│  Blockchain │───▶│  Webhook  │
│   Payment   │    │    Pays      │    │  Confirms   │    │   Sent    │
└─────────────┘    └──────────────┘    └─────────────┘    └───────────┘
     PENDING           PENDING           CONFIRMED         CONFIRMED

Stage 1: Payment Creation

When a customer checks out, your server creates a payment:

POST /api/merchant/v1/payments
{
  "amount": "50.00",
  "currency": "USDT",
  "network": "TRON",
  "tokenStandard": "TRC20",
  "metadata": {
    "product": "Premium Plan",
    "customer_id": "cust_abc"
  }
}

The API returns a unique TRON address:

{
  "paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "pending",
  "amount": "50.00",
  "currency": "USDT",
  "network": "TRON",
  "tokenStandard": "TRC20",
  "generatedAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "expiresAt": "2025-01-15T10:30:00.000Z"
}

Stage 2: Payment Page

Display a clear payment interface:

Amount: Exact USDT amount (e.g., "50.00 USDT")

Address: TRON address with copy button

QR Code: Scannable by mobile wallets

Countdown: Time remaining (30 minutes default)

Network: Clearly state "TRON (TRC-20)"

Important UX Considerations

Warn users about network selection (TRC-20, not ERC-20)

Show transaction fees are paid by sender

Provide wallet app deep links if possible

Stage 3: Blockchain Monitoring

Once the customer sends USDT:

Detection: Our scanner detects the transaction (~30 seconds)

Verification: Amount matches within tolerance (0.01 USDT)

Confirmation: Wait for 19 block confirmations (~1 minute)

During this time, you can poll for status:

GET /api/merchant/v1/payments/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Stage 4: Webhook Notification

When confirmed, we send a webhook:

{
  "id": "evt_a1b2c3d4_1705320600000",
  "type": "payment.confirmed",
  "createdAt": "2025-01-15T10:10:00.000Z",
  "data": {
    "paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "confirmed",
    "amount": "50.00",
    "currency": "USDT",
    "network": "TRON",
    "expectedAmount": "50.00",
    "receivedAmount": "50.00",
    "netAmount": "49.50",
    "feeAmount": "0.50",
    "txHash": "a1b2c3d4...",
    "generatedAddress": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "confirmations": 19,
    "metadata": { "product": "Premium Plan", "customer_id": "cust_abc" }
  }
}

Handling Edge Cases

Underpayment

If the customer sends less than required:

Payment is marked underpaid

Webhook sent with payment.underpaid event

receivedAmount, expectedAmount, and underpaidAmount fields show details

Consider your policy (refund, partial credit, etc.)

Overpayment

If the customer sends more:

Payment is marked overpaid

Webhook sent with payment.overpaid event

receivedAmount, expectedAmount, and overpaidAmount fields show details

Refund policy is at your discretion

Expiration

After 30 minutes without sufficient payment:

Status changes to expired

Webhook sent with payment.expired event

Funds sent after expiration require manual handling

Fee Calculation

Fees are calculated at payment creation:

fee_amount = (amount * fee_percent / 100) + fixed_fee
net_amount = amount - fee_amount

Example with 1% + $0.30:

Amount: $100.00

Fee: $1.00 + $0.30 = $1.30

Net: $98.70

Integration Checklist

[ ] Create payment on checkout

[ ] Display clear payment instructions

[ ] Handle webhook notifications

[ ] Implement signature verification

[ ] Process idempotently

[ ] Handle expiration gracefully

[ ] Test in sandbox first

Related Guides

Accept USDT Payments

Webhook Security

Pricing & Fees