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 Report 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 PaymentIntents 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

Get 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

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 ApplePay or GooglePay 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-demo.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?