Payment statuses
A PaymentIntent is the central entity in the Airwallex Payments API, representing your customer's intent to pay you and tracking the full lifecycle of a payment from creation to final payment. It is a stateful object that persists until the payment is either successfully completed or cancelled.
A single PaymentIntent can contain multiple PaymentAttempts.
- PaymentIntent: The container for the order, for example, "Customer wants to pay $100".
- PaymentAttempt: An individual try to pay, for example, "Attempt 1 failed due to insufficient funds," "Attempt 2 succeeded".
Typically, the status of the PaymentIntent is linked to the status of the latest PaymentAttempt, for example, Airwallex will mark a PaymentIntent as successful if the last payment attempt is successful, regardless of the status of previous attempts. Note that there may be exceptions.
Payments lifecycle
The PaymentIntent transitions through different statuses as the customer moves through the checkout flow--here's a simplified version of the status diagram.
| Status | Description | Emitted webhook | Required action |
|---|---|---|---|
REQUIRES_PAYMENT_METHOD | The PaymentIntent has been created, but no payment details have been provided yet, or the previous attempt failed. | payment_intent.created and payment_intent.requires_payment_method are emitted when a PaymentIntent is first created. When a PaymentIntent status is reverted due to a previous payment attempt failure, only payment_intent.requires_payment_method is emitted. | Collect payment details from the customer and call Confirm a PaymentIntent API endpoint. For transactions reverted from payment_intent.requires_customer_action, you should also check the failure reason of the previous attempt and display relevant error message to guide the customer to retry with another payment method. |
REQUIRES_CUSTOMER_ACTION | The payment requires additional action from the customer, such as 3D Secure authentication or a redirect to a digital wallet app, for example, Alipay, WeChat Pay. | payment_intent.requires_customer_action | Handle the next_action field in the response, for example, redirect the user or show a 3DS modal. |
REQUIRES_CAPTURE | The payment was authorized successfully, but funds have not been captured yet. Only applies if auto_capture is set to false in the PaymentIntent object. | payment_intent.requires_capture | Make a specific request to capture the funds within the authorization window (typically 5 days for cards but varies by payment method). For more information on the authorization window for various payment methods, see Place a hold on a payment method. |
PENDING | The payment is being processed asynchronously (common for local payment methods such as direct debits). | payment_intent.pending | Do nothing. Wait for the payment_intent.succeeded webhook. |
PENDING_REVIEW | The payment was successfully authorized, but it is currently under review for risk compliance. | payment_intent.pending_review | Do nothing. Wait for the payment_intent.succeeded webhook. |
SUCCEEDED | The payment has been successfully captured. Funds are guaranteed and will settle into your Airwallex Wallet. Note that settlement takes time, for example, T+2 days depending on the payment method's settlement schedule and your account's reserve plan. You can track it via Financial Transactions API API or the Airwallex web app. For how settlements work, see Settlements. | payment_intent.succeeded | Fulfill the order. |
CANCELLED | The PaymentIntent was manually cancelled by you, or the authorization expired before capture. | payment_intent.cancelled | Do not fulfill the order. Create a new PaymentIntent if the customer wishes to try again. |
Listen to webhooks to update your order database, especially for asynchronous payment methods where the user might close the browser before the API responds.