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_UPDATE and PAYMENT_REFUND events. 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

TransitionMeaning
ACTIVE -> COMPLETEDPayment executed successfully
ACTIVE -> CANCELLEDExecution failed and funds were reverted
COMPLETED -> CANCELLEDCumulative refunds reached the full payment amount

Timing expectations

PhaseTypical duration
STARTING to ACTIVEMilliseconds
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:

TypeSynthetic status after refundMeaning
TotalCANCELLEDFull amount was refunded, payment fully reversed
PartialCOMPLETEDOnly part of the amount was refunded

Use refund fields in synthetic data to classify final financial effect:

FieldValueMeaning
internalRefundtrueInternal rollback after failure
internalRefundfalseExternal reimbursement/refund case
amountToRefundstringReal 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

  1. Treat webhook events as primary signal.
  2. Use externalId to recognize the payment
  3. Re-fetch synthetic by ID before closing status in your system.
  4. Treat COMPLETED as operational success, not as an irreversible close point. Keep listening for refunds.
  5. Reconcile debit/credit impact with balance activities and snapshots when needed.


Did this page help you?