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
| Initial state | Result state | Description |
|---|---|---|
| - | pending | Order is created via the Merchant API. For more information, see: Merchant API: Create an order. |
pending | processing | A 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. |
processing | authorised | Payment passed the authentication and authorisation stage and transitions to authorised state. For more information about authentication and authorisation, see: Payment object lifecycle. |
processing | pending | If 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. |
authorised | completed | The payment transitions to captured, indicating that the order is complete. |
Payment object lifecycle
| Initial state | Result state | Description |
|---|---|---|
| - | pending | A 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. |
pending | authorised | Payment bypasses the authentication challenge due to meeting exemption criteria, directly transitioning to authorised state. Order transitions to authorised state.Intermediate states
|
pending | authentication_challenge | If required, the customer is prompted with an authentication challenge to verify their identity. For more information, see: 3D Secure overview. |
authentication_challenge | authorised | Upon successful authentication, the payment transitions to authorised state. Order transitions to authorised state.Intermediate states
|
authorised | captured | The payment amount is successfully captured. Order transitions to completed state. Intermediate states
|
captured | completed | Captured funds are settled on the merchant's account, marking the payment as completed. |
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.