• 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) or confirming (payment detected)
• expired: Invoice that received no payment or insufficient payment within its active period
  • Final state for invoices with exception = false
  • Can transition to paid if an exception payment is manually accepted by the merchant
• confirming: Payment detected with correct or excess amount, awaiting network confirmations
  • Transitions to: error (confirmation timeout) or paid (sufficient confirmations received)
• error: Transaction confirmation failed within 96-hour window
  • Final state, cannot transition further
• paid: Invoice fully processed with sufficient confirmations and credited to merchant account
  • Final state, represents successful payment completion

Exception

The unhandledExceptions flag identifies invoices requiring merchant attention due to payment anomalies:

• Overpayment (amount greater than requested)
• Underpayment (amount less than requested but potentially acceptable)
• Delayed payment (correct or incorrect amount sent to an expired invoice)

Invoices with unhandledExceptions = true share the following behavior:

1. Invoices are refundable from invoice url. However, only paying customer is allowed to request a refund from invoice url for security reasons. Merchant can initiate a refund from an invoice detail in their dashboard.

2. paid invoice. Only overpayment and not the whole amount is refundable. The invoice remains in the state paid all the time.

3. expired invoice. The whole amount is refundable. The merchant can review the invoice and accept the payment to his balance additionally. Once the payment is credited to merchant's balance the status of the invoice changes to paid. The invoice is no longer refundable and unhandledExceptions is set to false.

4. If the additional payment is sent to resolved (already refunded or credited) invoice unhandledExceptions is set to true again.

5. We do not mark invoices with an exception flag if the amount of overpayment or underpayment is very low and the refunding amount would cost more than the network fee or very close to the network fee.

6. Payment that matches rules specified in Dashboard in Underpayment threshold have unhandledExceptions set to false.

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).