Skip to main content

Expired Invoices

An invoice expires in one of two ways:
  1. The expiresInMinutes time limit is reached without full payment
  2. The invoice is manually cancelled via POST /api/v1/invoices/:invoiceId/cancel

The invoice.expired event


Handling expiry in your webhook


Giving the customer a second chance

To let the customer retry, create a new invoice and redirect them to it:

Bitcoin blocks can take 10–60 minutes. Set a minimum of 60 minutes for any invoice that may be paid with BTC to give customers enough time to complete the transaction.

Manually cancelling an invoice

Cancel a pending invoice before its natural expiry:
Cancellation immediately sets the invoice status to expired and fires the invoice.expired webhook.

Checkout countdown timer

Always show a countdown so customers know how long they have:

Late payments after expiry

If a customer sends funds to an expired invoice’s deposit address:
  • The payment is detected on-chain
  • It is not automatically settled — the invoice is closed
  • Contact Settlx support to manually process the payment