Guides • Accept Payments
Order and payment lifecycle
doc

Introduction to order and payment lifecycle in Merchant API

Welcome to our comprehensive guide on understanding the order and payment state flow within the Merchant API!

The role of order and payment objects

The Merchant API mainly operates with orders, which are the primary objects necessary for accepting payments.

An order represents a customer's intent to purchase goods and is the starting point for any transaction. Within each order, there can be multiple payment objects, representing different payment attempts associated with a single order. Once a successful payment is completed, no further payment attempts are allowed on that order.

Each order and payment object within the API has its own lifecycle, marked by specific status changes. These changes reflect the progression of an order or payment from creation to completion.

The following diagrams show the process and correlations of order and payment object state changes.

Order object lifecycle

Successful order state flow

Initial stateResult stateDescription
-pendingOrder is created via the Merchant API.

For more information, see: Merchant API: Create an order.
pendingprocessingA payment session begins when a customer is ready to finalise their purchase and presses the Pay button on the payment page or widget. A new payment object is created with pending state and linked to the order.

Order stays in processing state, until the current payment flow reaches a final state.
processingauthorisedPayment passed the authentication and authorisation stage and transitions to authorised state.

For more information about authentication and authorisation, see: Payment object lifecycle.
processingpendingIf the payment fails at any point during the order's processing state, the order status reverts to pending.

A new payment session will need to be initiated, creating a new payment object linked to the order.
authorisedcompletedThe payment transitions to captured, indicating that the order is complete.

Payment object lifecycle

Successful payment state flow

Initial stateResult stateDescription
-pendingA payment session begins when a customer is ready to finalise their purchase and presses the Pay button on the payment page or widget. A new payment object is created and linked to the order, when an order transitions to processing state.
pendingauthorisedPayment bypasses the authentication challenge due to meeting exemption criteria, directly transitioning to authorised state.

Order transitions to authorised state.

Intermediate states
  1. authorisation_started
  2. authorisation_passed
pendingauthentication_challengeIf required, the customer is prompted with an authentication challenge to verify their identity.

For more information, see: 3D Secure overview.
authentication_challengeauthorisedUpon successful authentication, the payment transitions to authorised state.

Order transitions to authorised state.

Intermediate states
  1. authentication_verified
  2. authorisation_started
  3. authorisation_passed
authorisedcapturedThe payment amount is successfully captured.

Order transitions to completed state.

Intermediate states
  1. capture_started
capturedcompletedCaptured funds are settled on the merchant's account, marking the payment as completed.

caution

Intermediate states are quick steps in the payment process. They are crucial for internal validations but often too rapid to be detected in status polls.

Actions or decisions should be based on the states described under Result states, merchants should not base any conditional logic on intermediate states.

Was this page helpful?