Payment Lifecycle
Invoice statuses
| Status | Meaning |
|---|---|
pending | Waiting for a transfer |
detected | A matching transfer is on chain, not yet final |
confirming | Transfer has ≥1 confirmation, waiting for finality |
paid | Confirmed and amount matches (within tolerance) |
underpaid | Confirmed but less than expected. Never auto-marked paid. |
overpaid | Confirmed and more than expected. Difference recorded; no auto refund. |
expired | Not paid before expires_at (late transfers within a 15-minute grace window are still accepted) |
cancelled | Cancelled via API while pending |
failed | The detected transfer was reverted or dropped |
CREATED → PENDING → DETECTED → CONFIRMING → PAID
PENDING → EXPIRED | CANCELLED
DETECTED/CONFIRMING → UNDERPAID | OVERPAID | FAILEDPayment statuses
detected → confirming → confirmed, or failed. A payment is one on-chain transfer applied to one invoice. With AGGREGATE_PAYMENTS several payments can settle one invoice; with the default ONE_PAYMENT_REQUIRED the first confirmed transfer decides the outcome.
Verification rules
A transfer becomes a payment only if all hold: correct network; token contract on the whitelist (the symbol alone is never trusted); recipient is a registered merchant address; the node reports the transaction as successful and its event log contains the exact transfer; exactly one open invoice matches deterministically. The browser never tells the backend a payment happened — the chain is the source of truth.
Confirmations
TRON blocks are ~3 seconds. A payment is confirmed once it has the network's required confirmations (default 19) and its block is reported as solidified by the network. Expect roughly one minute.