Set up the payment flow

🚧
Early release
Online payments is in early development (MVP). This section may change.

After a payment is authorised, you finish it with capture, cancel, refund or update. Each operation is allowed only in some states.

📘
Applies to authorise and capture methods
These states apply mainly to payment methods that authorise first and capture later, such as cards and some alternative payment methods. Some payment methods behave differently, because of scheme rules, acquirer capabilities or product configuration.

The simple lifecycle

Most integrations only need these states: creation, authorisation, capture, cancel, refund and failure.

stateDiagram-v2
    [*] --> CREATED : create session
    CREATED --> AUTHORIZED : authorized
    CREATED --> CANCELED : shopper or merchant cancels
    CREATED --> FAILED : failed
    AUTHORIZED --> AUTHORIZED : update (extend or adjust), if the acquirer approves
    AUTHORIZED --> CAPTURED : capture
    AUTHORIZED --> CANCELED : cancel
    CAPTURED --> REFUNDED : refund
    REFUNDED --> [*]
    CANCELED --> [*]
    FAILED --> [*]

The complete lifecycle

The complete lifecycle adds partial captures, several partial captures, partial cancels and several refunds. Use it for split shipments, order changes, omnichannel fulfilment and incremental reservation management. Both diagrams show the same lifecycle; this one has more detail.

stateDiagram-v2
    [*] --> CREATED : create session
    CREATED --> AUTHORIZED : authorized
    CREATED --> CANCELED : shopper or merchant cancels
    CREATED --> FAILED : failed
    AUTHORIZED --> AUTHORIZED : update
    AUTHORIZED --> PARTIALLY_CAPTURED : capture (partial)
    AUTHORIZED --> CAPTURED : capture (full)
    AUTHORIZED --> PARTIALLY_CANCELED : cancel (partial)
    AUTHORIZED --> CANCELED : cancel (full)
    PARTIALLY_CAPTURED --> PARTIALLY_CAPTURED : capture (partial)
    PARTIALLY_CAPTURED --> CAPTURED : capture (remaining) or last capture
    PARTIALLY_CANCELED --> PARTIALLY_CANCELED : cancel (partial)
    PARTIALLY_CANCELED --> CANCELED : cancel (remaining)
    CAPTURED --> PARTIALLY_REFUNDED : refund (partial)
    CAPTURED --> REFUNDED : refund (full)
    PARTIALLY_REFUNDED --> PARTIALLY_REFUNDED : refund (partial)
    PARTIALLY_REFUNDED --> REFUNDED : refund (remaining)
    REFUNDED --> [*]
    CANCELED --> [*]
    FAILED --> [*]

Update changes the amount or extends the authorization, if the acquirer approves. Last capture is a partial capture with cancelRemainingReservation set to true.

A last capture is a partial capture with cancelRemainingReservation set to true.

Which operation when

You want to	Use	Allowed when the payment is
Collect reserved money	Capture	Authorised, or partly captured
Release reserved money you won't capture	Cancel	Authorised, before it is fully captured
Return captured money	Refund	Captured, or partly captured
Keep a reservation valid longer, or change its amount	Update	Authorised
See what happened	Get payment status	Any state

Every operation needs the pspReference from when you created the payment, and every POST needs a new idempotency-key.