Settlement Records

Use the Settlement Record API to receive the full settlement details of a particular settlement batch or payment intent.

The Settlement Record API provides the same information as the Settlement ReportDocs but via JSON. The API can be queried using settlement batch ID or payment intent ID or both depending on your reconciliation use case.

How to use this API:

Step 1: Retrieve a settlement batch ID and/or payment intent ID.
You can obtain a settlement batch ID by calling the Get list of settlements endpoint. To query by a specific payment intent, retrieve the corresponding payment intent ID using the Get list of Payment Intents endpoint.

Step 2: Query the Settlement Record API.
Once you have the required identifiers, make a request to this API to retrieve detailed settlement records. Refer to the API Reference for request details and parameters.

This API supports keyset pagination using the page_after parameter. If the response includes additional pages, the has_more field will be set to true.

Endpoints

GET /api/v1/pa/settlement_records

List all Settlement Records

GET /api/v1/pa/settlement_records

Copy for LLMView as Markdown

Get Settlement Records by specifying the settlement (batch) unique identifier or payment intent unique identifier.

Query parameters

pagestring

Value from page_after.

page_sizeinteger

The number of items requested by page (default and max is 50).

payment_intent_idstring

The payment intent unique identifier of the settlement records.

settlement_idstring

The settlement(batch) unique identifier of the settlement records.

Response body - 200 OK

has_moreboolean

A flag which identifies whether there are more results.

itemsarray

List items.

items.account_idstring

Unique identifier of your account in Airwallex.

items.acquirer_reference_numberstring

A unique number assigned to a card transaction as it moves through the payment flow. It can be used by banks to help trace a transaction if it appears to be missing. An ARN will be available for Visa and Mastercard charges.

items.card_categorystring

Card category, such as consumer, commercial, if applicable.

items.card_fundingstring

Card funding type, such as credit, debit, prepaid, if applicable.

items.card_issuing_or_shopper_countrystring

Country the shopper's payment method was issued in, if applicable.

items.card_transaction_regionstring

Identifies what region the card transaction has been classified as, such as domestic, regional or international.

items.connected_account_idstring

Unique identifier of the connected account related to this transaction under the Payments for Platforms model, if applicable.

items.created_atstring

Timestamp of when the financial transaction was created.

items.customer_emailstring

Email of the customer, if applicable.

items.customer_idstring

Unique identifier of the customer in Airwallex, if applicable.

items.customer_namestring

Name of the customer, if applicable.

items.customer_phonestring

Phone number of the customer, if applicable.

items.descriptorstring

Transaction descriptor that is displayed to the shopper.

items.dispute_reasonstring

Dispute reason from the payment method provider. For more information, refer to https://www.airwallex.com/docs/payments/disputes/dispute-reason-codes.

items.dispute_reason_codestring

Dispute reason code from the payment method provider. For more information, refer to https://www.airwallex.com/docs/payments/disputes/dispute-reason-codes.

items.dispute_statusstring

The latest status of the dispute. For more information on dispute statuses, refer to https://www.airwallex.com/docs/payments/manage-payments/disputes/handle-disputes-on-the-airwallex-web-app.

items.exchange_ratenumber

Exchange rate used for converting the transaction amount into the settlement amount.

items.fee_details_listarray

List of related fee records.

items.fee_details_list.exchange_ratenumber

Exchange rate used for converting the fee currency into the settlement currency, if applicable.

items.fee_details_list.fee_currencystring

Three-letter ISO code for the fee.

items.fee_details_list.fee_subtotal_amountnumber

Fee amount in the fee currency.

items.fee_details_list.fee_typestring

Categorisation of fee types.

items.fee_details_list.incurred_atstring

Timestamp of when the fee was incurred at.

items.fee_details_list.payment_method_number_or_idstring

Unique identifier for the payment method used, such as card BIN and last 4 digits or Alipay and WeChat Pay unique identifiers.

items.fee_details_list.settlement_currencystring

Three-letter ISO code for the settlement currency of the fee.

items.fee_details_list.settlement_subtotal_amountnumber

Fee amount in the settlement currency.

items.fee_details_list.settlement_tax_amountnumber

Taxes associated with the fee in the settlement currency.

items.fee_details_list.settlement_total_amountnumber

Total amount of the fee after taxes are included, in the settlement currency.

items.fee_details_list.source_statusstring

Status of the source, for example: failed, success.

items.feesnumber

Amount of the total fees paid for the transaction in the settlement currency, exclusive of taxes.

items.gross_amountnumber

Amount of the transaction, converted into the settlement currency.

items.issuing_or_originating_bankstring

Name of financial institution that the shopper's payment method was issued from, if applicable.

items.merchant_customer_idstring

Unique identifier of the customer provided by you, if applicable. Maximum length is 64.

items.metadataobject

A set of key-value pairs that you can attach to the Settlement Record. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

items.net_amountnumber

Net amount of the transaction in the settlement currency, after subtracting the fees.

items.order_idstring

Unique identifier from your order system associated with a payment intent.

items.payment_attempt_idsarray

Unique identifiers for payment attempt associated with this payment.

items.payment_created_timestring

Time at which the payment intent was created.

items.payment_intent_idstring

Unique identifier for the payment intent.

items.payment_link_referencestring

Reference for the payment link input by your customer, if applicable.

items.payment_methodstring

The payment method used by the shopper for this transaction.

items.payment_method_typestring

Helps you identify the payment method, if applicable, for example: Card brand when Apple Pay or Google Pay are used: Visa, Mastercard, etc. Klarna: Pay Now, Pay Later, etc.

items.request_idstring

Unique identifier from your system associated to your request to Airwallex.

items.settled_atstring

Timestamp of when the financial transaction was settled into your wallet.

items.settlement_batch_idstring

Unique identifier associated with the batch settlement.

items.settlement_currencystring

Three-letter ISO code for the settlement currency of the transaction.

items.shipping_addressstring

First line of the shipping address associated with this transaction, if applicable.

items.shipping_citystring

City of the shipping address associated with this transaction, if applicable.

items.shipping_countrystring

Country of the shipping address associated with this transaction, if applicable.

items.shipping_namestring

Name on the shipping address associated with this transaction, if applicable.

items.shipping_postal_codestring

Postal code of the shipping address associated with this transaction, if applicable.

items.shipping_statestring

State of the shipping address associated with this transaction, if applicable.

items.source_entitystring

Source object associated with the transaction.

items.source_idstring

Unique identifier for the payment attempt, payment consent, refund, or dispute.

items.subscription_idstring

Unique identifier of the subscription related to this transaction, if applicable.

items.taxes_on_feesnumber

Amount of the total taxes on fees paid for the transaction in the settlement currency.

items.transaction_amountnumber

Amount of the transaction.

items.transaction_currencystring

Three-letter ISO code for the original currency sent to Airwallex for the transaction.

items.transaction_idstring

Unique identifier associated with the financial transaction.

items.transaction_typestring

Categorisation of financial transactions. Possible values: Payment, Payment Reserve Hold, Payment Reserve Release, Split, Split Reversal, Dispute, Dispute Reversal, Dispute Lost, Dispute Won, Pre Chargeback Accepted, Pre Chargeback Withdrawn, Refund Pre Chargeback Accepted, Refund Chargeback Received, Refund Chargeback Withdrawn, Refund, Refund Reversal, Refund Failure, Account Verification, Verification.

page_afterstring

Page after.

Errors

Error status	Description
400	Bad Request. Possible error codes: `resource_not_found` (`settlement_id` or `payment_intent_id` not found), `validation_error` (e.g. invalid `page_size`), `configuration_error` (Invalid request against merchant configuration. Please contact your account manager.)
401	Unauthorized. Possible error codes: `unauthorized`
403	Forbidden
404	Not Found
500	Server Error. Possible error codes: `internal_error`

GET /api/v1/pa/settlement_records

$curl --request GET \
>  --url 'https://api.sandbox.airwallex.com/api/v1/pa/settlement_records?settlement_id=bat_20250305_AUD_1' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "has_more": true,
3  "items": [
4    {
5      "account_id": "acct_NmdN7NpxM_KucIpNwui7GQ",
6      "card_category": "Consumer",
7      "card_funding": "Credit",
8      "card_issuing_or_shopper_country": "AUS",
9      "card_transaction_region": "Asia",
10      "created_at": "2025-03-05T20:10:00Z",
11      "customer_email": "[email protected]",
12      "customer_id": "cus_sgstf9vlwh571d5ws2z",
13      "customer_name": "Danny Jones",
14      "customer_phone": "123456789",
15      "descriptor": "vip8888",
16      "exchange_rate": 1,
17      "fee_details_list": [
18        {
19          "exchange_rate": 1,
20          "fee_currency": "AUD",
21          "fee_subtotal_amount": 3,
22          "fee_type": "Payment method fee",
23          "incurred_at": "2025-03-27T03:27:34-0600",
24          "payment_method_number_or_id": "abc****abc",
25          "settlement_currency": "AUD",
26          "settlement_subtotal_amount": 3,
27          "settlement_tax_amount": 1,
28          "settlement_total_amount": 4,
29          "source_status": "Paid"
30        }
31      ],
32      "fees": -3,
33      "gross_amount": 5000,
34      "issuing_or_originating_bank": "National Australia Bank",
35      "merchant_customer_id": "a336bb7a-1ce6-437a-b800-723851896038",
36      "metadata": {
37        "foo": "bar"
38      },
39      "net_amount": 4996,
40      "order_id": "46e06c0a-26ec-419c-8f42-0c33212bb13f",
41      "payment_attempt_ids": [
42        "att_sgstfl9zth571d6cvhq_d61cd3"
43      ],
44      "payment_created_time": "2025-03-05T20:05:35Z",
45      "payment_intent_id": "int_sgstfl9zth571d61cd3",
46      "payment_method": "ApplePay",
47      "payment_method_type": "Visa",
48      "request_id": "a7c419e1-e43a-4681-8951-02981f3150e0",
49      "settled_at": "2025-03-05T23:20:00Z",
50      "settlement_batch_id": "bat_20250305_AUD_1",
51      "settlement_currency": "AUD",
52      "shipping_address": "123 Baker Street",
53      "shipping_city": "London",
54      "shipping_country": "ENG",
55      "shipping_name": "violet client",
56      "shipping_postal_code": "100234",
57      "shipping_state": "London area",
58      "source_entity": "Payment Attempt",
59      "source_id": "att_sgstfl9zth571d6cvhq_d61cd3",
60      "taxes_on_fees": -1,
61      "transaction_amount": 5000,
62      "transaction_currency": "AUD",
63      "transaction_id": "ftx_ymUW4ZTiPJSyOxfYBFkXfg",
64      "transaction_type": "Payment"
65    }
66  ],
67  "page_after": "<string>"
68}

Was this section helpful?