Invoice lifecycle
An invoice travels from creation to being closed or expiring. This section describes the states it can be in, how it moves between them, and what the merchant can do at each step.
Invoice statuses
| Status | API value | Description | Included in payment search |
|---|---|---|---|
| Unpaid | unpaid | The invoice is issued, the payment deadline has not passed, no payment received | Yes |
| Paid | paid | A payment is found and matched to the invoice | No |
| Expired | expired | The payment deadline has passed, no payment received | Yes, for one more hour after expiry |
| Canceled | canceled | The invoice is canceled by the merchant manually or via the API | No |
Status transitions
- Invoice creation. The invoice immediately gets the Unpaid status.
- Unpaid → Paid. A payment for the exact invoice amount arrived, or the merchant matched a payment manually.
- Unpaid → Expired. The payment deadline passed with no payment received.
- Unpaid → Canceled. The merchant canceled the invoice.
- Expired → Paid. The payment arrived within an hour after expiry and was found automatically, or the merchant matched it manually.
- Canceled. A final state; there is no way back.
An invoice in the Paid status does not change state either—it cannot be paid again or canceled.
Payment deadline
The deadline is set at invoice creation and ranges from 30 minutes to 12 hours. Allowed values: 30 minutes, 1 hour, 3 hours, 6 hours, 12 hours.
Until the deadline, the customer sees the payment form and can pay the invoice. After expiry, the invoice moves to Expired and the payment form no longer offers payment.
Both extremes come at a price. A short deadline is risky on slow networks—the customer may not make it in time. A long one widens the gap between the rate at invoice creation and the rate at payment.
Payment search window
The payment search continues for one more hour after the payment deadline—to account for slow networks, where a transaction may confirm after the invoice has formally expired. All this time the customer sees the invoice as expired, but when a payment for the right amount arrives, it automatically moves to Paid with all the notifications.
Hence the rule for integrators: do not reject a payment notification because the deadline has passed—that check cuts off a share of real payments.
Canceling an invoice
You can cancel an invoice if it contains a mistake. Cancellation requires two conditions:
- The invoice is not paid—that is, it is in the Unpaid status
- No one has opened the invoice's payment page; the view counter is zero
The second condition protects against canceling an invoice the customer has already seen and possibly started paying.
Cancellation is irreversible. A canceled invoice is excluded from the payment search, and a payment cannot be matched to it even manually. If payment is likely, wait for the deadline to pass instead of canceling—an expired invoice can still be closed with a payment.
What is locked at creation and what is recalculated at payment
At invoice creation, the service converts the fiat amount into crypto at the current rate and locks the resulting amounts in for the invoice. These are the amounts the customer sees, and these are what the service looks for on-chain. The rate no longer affects them: no matter how much time passes, the customer pays exactly the locked-in amount.
At the moment of payment, the accounting amounts are recalculated:
| Field | What happens |
|---|---|
amountFiat | The original invoice amount in fiat currency. Never changes |
amountFiatUSD | Overwritten with the amount actually received, converted to USD at the rate at the moment of payment |
commissionFiatUSD | Recalculated from the new amountFiatUSD value at the project's fee rate |
Because of rate movement, these values can differ from the original ones even when the payment is exact. To reconcile with the order in your store, use amountFiat—the only amount that stays unchanged.
Notifications along the invoice's life
Notifications are configured per project. An invoice has two of them:
- Incoming payment. Sent to email and Telegram when any incoming transaction is detected on your wallet, whether or not it matched an invoice.
- Invoice paid. Sent to email, Telegram, and the Webhook URL the moment the invoice moves to Paid—on both automatic and manual matching.
This gives a simple diagnostic rule: if an incoming payment notification arrived but no paid-invoice notification followed, the payment did not match because of an amount mismatch and needs manual handling.
Returning the customer to the store site
In the project settings, you can set two URLs the customer returns to from the payment page:
- Successful URL—automatic redirect after the invoice is paid
- Unsuccessful URL—automatic redirect when an expired or canceled invoice is opened
Each URL is enabled separately. If a URL is not set, the customer stays on the payment page and sees the invoice status.
The uid parameter—the invoice identifier for the customer—is appended to the URL: https://example.com/order/success?uid=AFhygKX21ecd. The store uses it to find the order and show the customer its own page.
Landing on these URLs does not confirm payment—the customer can open the link manually. Fulfill orders based on the webhook or after checking the invoice status via the API.