Skip to main content

Payment lifecycle

Last updated: 2026-09-26

Use the latest accepted payment order status as the business outcome. Redirects, payment instructions, and HTTP acceptance are not final success signals.

Statuses​

  • PAYMENT_ORDER_STATUS_CREATED
  • PAYMENT_ORDER_STATUS_PENDING
  • PAYMENT_ORDER_STATUS_COMPLETED
  • PAYMENT_ORDER_STATUS_FAILED
  • PAYMENT_ORDER_STATUS_CANCELLED
  • PAYMENT_ORDER_STATUS_EXPIRED

PENDING updates may repeat. COMPLETED, CANCELLED, and EXPIRED end the normal payment flow. A completed pay-in can later receive a correction of the same payment, so continue accepting verified updates after completion.

During a correction you may receive FAILED for the previously completed payment and then another COMPLETED update with a corrected amount. You may also receive only the corrected completion. Neither is a second payment. Not every FAILED update is followed by a new completion: read the current payment and reconcile the updates together, rather than assuming the next state. Contact support if the result remains unclear.

FAILED is not always final: a late confirmation can change it to COMPLETED. Delivery order alone does not establish the latest payment state. Processing must be idempotent and use the latest reconciled result.

Reconciliation​

  1. Persist the payment order ID and your merchantReference when you create or initialize a payment.
  2. Verify and process webhook deliveries idempotently.
  3. Read the payment by ID when a webhook is delayed, after a customer redirect, or during reconciliation.
  4. Use lookup by merchant reference to recover the current attempt. Keep references distinct across pay-ins and payouts, and use the payment ID for an older attempt after permitted reference reuse.
  5. Finalize your merchant workflow only from the latest reconciled status.

For a completed pay-in, use the recognized actualAmount when crediting your customer, once per payment ID. A repeated read or a different webhook delivery ID must not create another credit. For payouts, actualAmount supports payout reconciliation. See the amount fields for gross-value and historical-payment semantics. A later webhook can correct the amount on the same payment; keep that update for reconciliation instead of treating it as another payment or silently discarding it. See Later amount corrections.

See Payments API for read operations, the PaymentOrder object for exact fields, and Webhooks for delivery and signature rules.