The Structure of a Crypto Invoice
A crypto invoice, as generated by a payment gateway, contains a minimum set of fields that collectively define a complete payment request. Understanding what each field does clarifies how the invoice functions as both a payment instruction and a reconciliation record:
● Invoice ID: A unique gateway-generated identifier for this specific invoice. Used for internal tracking and webhook references.
● Order ID (merchant reference): The merchant's own order identifier, passed to the gateway at invoice creation and returned in all gateway communications about this invoice.
● Invoice status: The lifecycle state — Created, Pending (payment detected, awaiting confirmations), Confirmed, Expired, Underpaid, Overpaid.
● Requested fiat amount and currency: The invoice value in the merchant's base currency (e.g., €150.00 EUR). This anchors the price lock calculation.
● Payment address: The unique blockchain address to which the customer must send payment.
● Required crypto amount: The exact cryptocurrency amount the customer must send, calculated from the fiat amount at the current rate. Displayed to sufficient decimal precision for the asset (8 for BTC, 6 for USDT).
● Rate and rate timestamp: The exchange rate used to calculate the crypto amount, and the time at which the rate was locked.
● Expiry time: The Unix timestamp or ISO datetime at which the invoice expires if unpaid.
● Accepted cryptocurrency: The specific asset and network expected (e.g., USDT on TRC-20 rather than any USDT).
● Confirmation threshold: How many block confirmations are required before the invoice is considered complete.
The Invoice Lifecycle — From Creation to Resolution
Every crypto invoice passes through a defined lifecycle, and the gateway's operations depend on correct state transitions at each stage. The lifecycle typically follows this sequence:
Created: The invoice exists in the gateway's database and a unique payment address has been generated. No payment has been detected.
Pending: A transaction to the payment address has appeared in the mempool (zero confirmations). The gateway notifies the merchant that a payment is in progress and begins monitoring confirmations.
Confirmed: The transaction has reached the required confirmation threshold. The merchant's gateway balance is credited and a confirmed webhook fires. Order fulfilment should be triggered here.
Expired (unpaid): The payment window elapsed with no payment detected. The invoice is closed; the merchant's system should mark the order as abandoned.
Expired (partially paid): The payment window elapsed with a payment detected below the underpayment tolerance. Requires manual resolution.
Overpaid: Payment received exceeds the invoice amount plus the overpayment tolerance. Triggers the gateway's overpayment handling policy.
Compliance Note: This glossary entry is provided for general educational purposes only and does not constitute financial, investment, legal, or tax advice. Industry terminology may vary across jurisdictions and providers; definitions herein may not directly reflect the specific features, terms, or specifications of Finassets' services. For details on Finassets' offerings, please refer to official product documentation or contact our team directly.