Payment lifecycle
Payment lifecycle
QR payment execution is asynchronous and state-driven.
After confirmation (POST /v2/synthetics/qr-payment), monitor lifecycle through webhooks and queries.
Prerequisites
- A configured webhook endpoint for
SYNTHETIC_STATUS_UPDATEandPAYMENT_REFUNDevents. See Webhooks. - A completed payment via
POST /v2/synthetics/qr-payment.
State diagram
[STARTING]
|
v
[ACTIVE] ──────────────────────────> [COMPLETED]
| |
| (failure / provider rejection) | (later refunded)
v |
[CANCELLED] <─────────────────────────────┤ (full refund)
|
[COMPLETED] (one or more partial refunds)
All QR payment synthetics pass through ACTIVE before reaching an operational result. STARTING is transient and typically not observed in practice. A payment may remain in ACTIVE status while the bank rail has not yet confirmed the transfer: this is normal and expected.
Lifecycle transitions
| Transition | Meaning |
|---|---|
ACTIVE -> COMPLETED | Payment executed successfully |
ACTIVE -> CANCELLED | Execution failed and funds were reverted |
COMPLETED -> CANCELLED | Cumulative refunds reached the full payment amount |
Timing expectations
| Phase | Typical duration |
|---|---|
STARTING to ACTIVE | Milliseconds |
ACTIVE to COMPLETED | ~2s to ~8s (depends on payment rail) |
COMPLETED to CANCELLED (refund) | Minutes to days (depends on merchant/bank) |
Payment rails in some countries (Bolivia, Colombia batch windows) may extend processing time. Supported countries: see Coverage.
Refund semantics
Refunds can be total or partial, and partial refunds can happen more than once:
| Type | Synthetic status after refund | Meaning |
|---|---|---|
| Total | CANCELLED | Full amount was refunded, payment fully reversed |
| Partial | COMPLETED | Only part of the amount was refunded |
Use refund fields in synthetic data to classify final financial effect:
| Field | Value | Meaning |
|---|---|---|
internalRefund | true | Internal rollback after failure |
internalRefund | false | External reimbursement/refund case |
amountToRefund | string | Real refund amount (can be partial) |
Each refund also appends a REFUND stage to the synthetic. That stage includes refundId, totalAmount, totalAmountToRefund, and fullyRefunded. The total* fields are cumulative across all refunds, not just the latest one.
A partial refund never moves the synthetic to CANCELLED. The synthetic only transitions to CANCELLED when the cumulative refunded amount equals the original payment amount (fullyRefunded: true on the latest refund stage). While the cumulative total is below the original, the synthetic stays COMPLETED no matter how many partial refunds arrive. Reconcile against totalAmount / totalAmountToRefund, not the latest amount / amountToRefund.
Since partial refunds do not change the synthetic status, the SYNTHETIC_STATUS_UPDATE webhook alone is not enough to detect them. To handle refunds, you must listen to the PAYMENT_REFUND webhook and use its cumulative refund fields.
Integration recommendation
- Treat webhook events as primary signal.
- Use externalId to recognize the payment
- Re-fetch synthetic by ID before closing status in your system.
- Treat
COMPLETEDas operational success, not as an irreversible close point. Keep listening for refunds. - Reconcile debit/credit impact with balance activities and snapshots when needed.
Updated 27 days ago