Payments data model

Copy for LLMView as Markdown

Understanding the core payments objects and their relationships is essential for building a robust, scalable integration. The data model supports different checkout experiences, from guest checkout to recurring payments, and forms the basis for financial reconciliation.

Core objects

Every transaction revolves around the PaymentIntent. This central object orchestrates the entire payment lifecycle, linking the shopper (Customer object) and their payment instrument (PaymentMethod object) to each PaymentAttempt, the resulting funds movement (settlement) and any post-payment operations such as refunds (Refund object) and disputes (PaymentDispute object). For returning customers, a PaymentConsent ties the PaymentIntent to a previously authorized PaymentMethod, enabling off-session payments without the shopper re-entering their details.

You can think of the model in simple terms: the PaymentIntent is the order request, the Customer is the shopper, the PaymentMethod is the instrument (card or digital wallet) used to pay, PaymentAttempt is the attempt to pay for the order, and settlement is the actual movement of funds into your Airwallex Wallet balance.

PaymentIntent

The PaymentIntent API is the source of truth for a transaction lifecycle. It represents your customer's intent to pay and tracks state from creation through successful capture or cancellation. It holds the amount, currency, and current payment status, for example, REQUIRES_PAYMENT_METHOD, REQUIRES_CUSTOMER_ACTION, or SUCCEEDED. For the full status lifecycle, see Payment statuses.

Each PaymentIntent ties together the shopper (via customer_id), the payment instrument used (PaymentMethod or PaymentConsent), all PaymentAttempts on that order, and any downstream objects such as refunds, disputes, financial transactions, and settlements that result from the payment.

PaymentAttempt

A PaymentAttempt API object represents individual attempts to fulfill a PaymentIntent using a specific payment method. When the shopper submits payment details and clicks Pay, Airwallex creates a new PaymentAttempt linked to the same PaymentIntent. Each attempt has its own status (for example, AUTHORIZED, FAILED, or AUTHENTICATION_REDIRECTED) and tracks the specific payment method used and any failure reasons.

If an attempt fails (for example, insufficient funds, incorrect CVV, 3DS authentication declined), the PaymentIntent remains open so you can prompt the shopper to retry with another method, creating additional attempts instead of a new order. This allows you to track all payment attempts for an order in one place while preserving the failure history for fraud analysis and retry optimization.

Refunds can reference payment_intent_id or payment_attempt_id. Disputes reference the originating PaymentIntent and include the related attempt, so you can trace issues back to the exact authorization and the original order.

Customer

The Customer API object represents the identity of the shopper across multiple orders. It stores persistent attributes such as email and phone. A Customer is optional for guest checkout, but required if you want to save payment details for future use. See Credential on File (CoF) payments.

A single Customer can be associated with many PaymentIntents and can own multiple saved PaymentMethods and PaymentConsents, giving you a consolidated view of their transaction history and the credentials you are allowed to reuse.

If you use Airwallex Billing (subscriptions, invoicing, dunning), you must use the Billing Customer API object, which represents the customer for subscriptions and invoices. Note that Customer and BillingCustomer objects are different, and you must map them in your system when you use both. Billing stores reusable instruments for charges through PaymentSource API.

PaymentMethod

The PaymentMethod API is the secure, tokenized payment instrument used to pay, such as a card, direct debit mandate, or digital wallet identifier. Airwallex creates PaymentMethods when shoppers enter payment details through a UI element (for example, Hosted Payment Page, Drop-in Element, or Embedded Elements) or when you call the PaymentMethods API API.

A PaymentMethod can be used for multiple transactions (multiple PaymentIntents and multiple PaymentAttempts). It can be attached directly to a PaymentIntent for a one‑time payment, or stored against a Customer so that the same instrument can be reused for future checkouts.

When you enable card‑on‑file or recurring flows, the PaymentMethod referenced by a PaymentConsent becomes the credential that subsequent PaymentIntents use without re‑entering full details.

With Billing, you must use a PaymentSource API that links a funding instrument to a Billing Customer API for subscriptions, invoices, and other billing-driven charges.

PaymentConsent

A PaymentConsent API captures the shopper’s authorization for you to charge a saved PaymentMethod in the future, often when the shopper is not actively in your app (off‑session). It links a specific Customer (via customer_id) to a specific PaymentMethod (via payment_method_id) and defines how that credential may be reused.

Airwallex creates a PaymentConsent when you confirm a PaymentIntent with credential storage enabled, for example by including customer_id and payment_consent on Confirm a PaymentIntent API, or by calling Create a Payment Consent API for some local payment method flows. The response includes a payment_consent_id that you store for subsequent charges. Subsequent PaymentIntents reference this payment_consent_id to prove authorization and to ensure that retries, installments, or subscription renewals all run against the correct saved agreement. The consent distinguishes between customer‑initiated transactions (CIT), where the shopper actively triggers the payment, and merchant‑initiated transactions (MIT), where you automatically charge the saved method for subscriptions or top-ups.

For implementation details, see Credential on File (CoF) payments and Save and reuse payment details.

Refunds

A Refund API represents the reversal of all or part of a successful PaymentIntent. Each refund points back to the original payment via payment_intent_id or payment_attempt_id, so you can see which order and which authorization is being adjusted. When you create a refund, Airwallex generates additional financial transactions that reduce your future settlement amounts while keeping the relationship to the original payment intact for reporting and reconciliation.

PaymentDispute

A PaymentDispute API is created when a shopper or their payment provider contests a transaction that previously succeeded. The PaymentDispute object always references the originating PaymentIntent, allowing you to see which order and which attempts are under review, and to attach evidence accordingly. As the dispute progresses through stages (for example, request for information, chargeback), Airwallex records the associated debits and credits as financial transactions against that PaymentIntent so you can track the full impact on your balances.

FundsSplit

A FundsSplit allocates captured funds from a PaymentIntent to one or more destination wallets, typically for marketplace or platform flows where you need to distribute funds between your platform and connected accounts. You can create multiple FundsSplits for one PaymentIntent, release remaining split amounts later, and use metadata to track business context for each allocation. For API details, see Create a FundsSplit API and Release a FundsSplit API.

Funds splits are commonly created after payment capture, but some integrations predefine split behavior and then manage release timing based on fulfillment, refund windows, or risk checks. For implementation patterns, see Manage funds split.

FundsSplitReversal

A FundsSplitReversal moves previously split funds back from the destination wallet to the source side when the original allocation needs to be corrected. You can create partial reversals multiple times against the same FundsSplit until the full split amount is reversed. This is useful when order amounts change, split instructions were incorrect, or you need to realign balances before or after post-payment operations.

FundsSplitReversal is independent from refund creation. You can decide whether and when to reverse a split based on your platform's settlement and reconciliation model. For API details, see Create a FundsSplitReversal API. For product guidance, see Reverse split funds.

Financial reconciliation objects

It is important to distinguish between the intent to pay and the actual movement of funds. A PaymentIntent in SUCCEEDED status does not mean funds have reached your Airwallex Wallet balance yet.

Settlements

Settlement is the process of moving funds from a customer's payment method, for example, card, bank transfer, local payment method, or direct debit, into your Airwallex Wallet, and once released from any reserves, appear in your available balance. In addition to the payment method settlement schedule (for example, T+2 days, where "T" is the transaction capture date) and reserve plan, there are other factors that might contribute to settlement delays. See Settlements and Settlement Records API for more information.

FinancialTransactions

FinancialTransactions API are the ledger‑level records that describe how money moves for each payment and post‑payment event. For every payment, refund, or dispute, Airwallex creates one or more financial transactions that capture principal amounts, processing fees, FX adjustments, reserves, and chargeback movements. These entries are grouped into daily batches and rolled up into Settlements that update your Wallet balances, while still preserving the links back to the originating PaymentIntents for accounting and reporting.

How objects fit together

These integration patterns illustrate how the various payment objects combine to process payments.

One-off payment

For one-off guest checkout (no saved payment details):

Server: Create a PaymentIntent with the order amount and currency using Create a PaymentIntent API.
Client: Collect payment details through your integration option. Hosted Payment Page, Drop-in Element, and Embedded Elements handle PaymentMethod creation for you. With Native API, PaymentMethods API API tokenizes the instrument and returns a payment_method_id.
Client or server: Confirm the PaymentIntent. When confirmation succeeds, the PaymentIntent status becomes SUCCEEDED (or REQUIRES_CAPTURE if you authorize first and capture later).

No Customer object is required for guest checkout. For implementation steps, see Payments quickstart.

Recurring payments

To charge a saved payment method:

Server: Create a Customer API if the shopper is new.
Client or server: Save payment details by confirming a PaymentIntent with customer_id and credential storage enabled, or by following the save-and-reuse flow for your integration option. Airwallex creates a PaymentMethod and PaymentConsent and returns a payment_consent_id.
Server: Create a PaymentIntent with customer_id and the amount to charge.
Server: Confirm the PaymentIntent for a subsequent charge, specifying whether the payment is a customer-initiated transaction (CIT) or merchant-initiated transaction (MIT):

CIT: The shopper actively triggers future payments, for example, one-click checkout or topping up a wallet. The shopper is present and may need to verify the payment with CVV or 3D Secure.
MIT: You automatically charge the saved method without the shopper's active involvement, for example, subscription renewals, installment payments, or account auto-top-ups.

Depending on your integration option and the use case, you can reference a combination of PaymentConsent ID, PaymentMethod ID, or Customer ID in subsequent payments to charge the saved payment method. For implementation steps, see Save and reuse payment details.

Working with the data model

Store Airwallex IDs

In your database, create a mapping between your internal identifiers and Airwallex object IDs such as order ID (Airwallex payment_intent_id), user ID (Airwallex customer_id), and subscription ID (Airwallex payment_consent_id).

This bidirectional mapping is essential for reconciliation, processing refunds, responding to disputes, and providing customer support. When you receive webhooks, the payload includes these Airwallex IDs, allowing you to update the corresponding records in your system.

Use webhooks for final state

Do not rely only on the frontend to know that a payment succeeded as the user may close the browser before redirect. Use webhooks (payment_intent.succeeded) as the definitive signal to fulfill orders and update your system. For more information, see Payments webhooks.