Invoice Lifecycle

Possible invoice statuses

The full list of invoice statuses can be seen below:

• prepared: Initial state where the customer selects their preferred payment method
  • This state exists only when an invoice is created with invoice.currencyTo = null
  • Transitions to: active (when payment method selected) or expired (after 15 minutes of inactivity)
• active: Invoice with complete payment instructions including crypto address, amount, and currency
  • Default active period: 15 minutes (configurable in Invoice Settings)
  • Transitions to: expired (timeout or insufficient payment received) or confirming (payment detected)
• expired: Invoice that received no payment or insufficient payment within its active state period
  • Final state for invoices with unhandledExceptions = false
  • Can transition to paid if an exception payment is manually accepted by the merchant
• confirming: Payment detected with correct or excess amount, awaiting required network confirmations
  • Transitions to: error (confirmation timeout) or paid (sufficient confirmations received)
  • If additional Travel Rule documentation is required it transitions to pending_verification instead
• error: Transaction confirmation failed within 96-hour window
  • Can be moved to paid with a manual action
• pending_verification: More information from the customer is required to satisfy Travel Rule documentation
  • If the additionally requested information is provided the funds are credited to you and the invoice moves to state paid
  • If the information is not provided in time the Invoice moves to state expired
• paid: Invoice fully processed with sufficient confirmations and credited to merchant account
  • Final state, represents successful payment completion

Data Purging

Please note that invoices which transition directly from prepared to expired status (i.e. those which never had their customerCurrency (or more generally payment method) set are subject to data purging after some retention period (e.g. a year).