Payments and statuses
An invoice describes an order. A payment is a specific attempt to pay it. A payment attempt and the availability of its link are separate states.
On this page
The payment record#
The invoice stores order terms; payment identifies its gateway operation. The first launch reserves one durable binding and a server Idempotency-Key. After dispatch begins, another method cannot create a second charge on the same invoice.
GET /api/payment-links and GET /api/v1/payments return link.payment to the owner. The link’s active/paused/cancelled/expired status is separate from payment state. A customer can only read their operation through the random checkout token.
| Data | Purpose |
|---|---|
| Identifier and order | Associate the attempt with a purchase |
| Base amount and currency | The calculation base |
| Payment method | Applicable fee and tax |
| VAT payer | Who covers the tax |
| Fee, VAT and totals | Saved calculation |
| Status and time | Current transaction state |
| Gateway event reference | Server confirmation source |
Live operation states#
The demo uses separate test records. Changing a demo state does not confirm a real payment or change financial records.
| Status | Meaning |
|---|---|
| pending | Operation created; awaiting action or a result |
| requires_action | A bank code or customer confirmation is required |
| processing | The provider is still confirming the result |
| succeeded | The server verified the exact payment |
| failed | Attempt ended without confirmed payment |
| expired | Instructions expired; reconciliation remains available |
| review_required | Additional review is needed; do not pay again |
| partially_paid | Only part of the amount received; do not create another payment |
| partially_refunded | Part of the payment was refunded |
| refunded | Refund confirmed |
| disputed | The operation is disputed |
The source of truth#
A signed webhook triggers an authenticated read of the exact gateway operation. IDs, order, currency, method, base and final amounts, live mode and monotonic version are validated. An incoming event name alone is not proof of money.
State, receipt and the merchant event commit atomically. Older responses cannot overwrite a newer version; duplicates do not fulfil twice, and pending cannot replace a confirmed payment. These records do not automatically create a withdrawable balance or payout.
When the result is unknown#
- 1
Keep the original invoice and operation identifier.
- 2
Read GET /api/checkout/{token}/status; it does not create a charge.
- 3
Use POST /api/checkout/{token}/reconcile when explicit reconciliation is needed.
- 4
Do not change method, amount or idempotency key after an uncertain result.