Changelog

The following lists the backwards-incompatible changes to Airwallex's API.

To avoid breaking existing integrations, all backwards-incompatible changes are covered by versioning. See the previous section for further details.

It includes a list of all affected endpoints to assist in identifying any migration work required. Please refer to the relevant version's documentation for full details of each affected endpoint's new contract.

If you have further questions or concerns please contact our support team.

2026-07-17

country_code is now required in the account address objects below. Previously country_code was optional in these addresses; requests that omit it in the cases described are now rejected with a validation error, ensuring a country can always be determined for each provided address.

Affected endpoints:
- POST /api/v1/accounts/create
- POST /api/v1/accounts/{id}/update
Changes:
- account_details.business_details.business_address.country_code: now required for non-registered sole proprietors and businesses that do not have a business registration country (on update, when business_address is provided).
- account_details.business_details.registration_address.country_code: now required for all business types except non-registered sole proprietors and businesses that do not have a business registration country. If the business has no registration country, provide it in business_address.country_code instead (on update, when registration_address is provided).
- account_details.individual_details.residential_address.country_code: now required (on update, when residential_address is provided).
The standalone lifecycle_id is removed from the Issuing Authorizations and Transactions APIs. Its value is now provided by the card_transaction_data object — which is available across all API versions — as its card_transaction_lifecycle_id child, alongside the other card transaction identifiers.

Affected endpoints:
- GET /api/v1/issuing/authorizations, request and response
- GET /api/v1/issuing/authorizations/{id}, response only
- GET /api/v1/issuing/transactions, request and response
- GET /api/v1/issuing/transactions/{id}, response only
Changes:
- lifecycle_id: removed from the response. Its value is now returned as card_transaction_data.card_transaction_lifecycle_id.
- lifecycle_id: removed as a query parameter from the List authorizations and List transactions endpoints.
- card_transaction_data: not new to this version — this object is available across all API versions and carries the card transaction identifiers for each authorization and transaction (omitted for transactions created before January 2025). It contains:
  - card_transaction_lifecycle_id: links related transactions belonging to the same card payment — such as authorizations, reversals, captures, and refunds — under a single lifecycle. Same value as the removed lifecycle_id.
  - card_transaction_id: identifier of the card transaction. Retrieve its details via GET /api/v1/issuing/card_transactions/{id}.
  - card_transaction_event_id: identifier of the individual card transaction event within the lifecycle; the closest equivalent of the transaction_id field.
Issuing webhook events now carry a card_transaction_data object with the card transaction identifiers, so you can correlate webhook payloads with the Card Transactions model (Lifecycle → Card Transaction → Transaction Event) without subscribing to new event types. The object is omitted for events raised on a transaction created before January 2025 (one with no card transaction identifiers).

Affected webhook events:
- issuing.transaction.succeeded
- issuing.transaction.failed
- issuing.transaction_dispute.created
- issuing.transaction_dispute.submitted
- issuing.transaction_dispute.accepted
- issuing.transaction_dispute.rejected
- issuing.transaction_dispute.cancelled
- issuing.transaction_dispute.expired
- issuing.transaction_dispute.won
- issuing.transaction_dispute.lost
- issuing.transaction_dispute.modified
Changes:
- data.card_transaction_data: added to each event above. It contains the same child items returned by the Authorizations and Transactions APIs:
  - card_transaction_lifecycle_id: the card transaction lifecycle identifier (same value as the old lifecycle_id).
  - card_transaction_id: identifier of the card transaction. Retrieve its details via GET /api/v1/issuing/card_transactions/{id}.
  - card_transaction_event_id: identifier of the individual card transaction event within the lifecycle.

2026-06-30

Specific risk_declined cases are now returned with more accurate error codes:

Affected endpoints:
- POST /api/v1/pa/payment_intents/create
- POST /api/v1/pa/payment_intents/{id}/confirm
- POST /api/v1/pa/payment_intents/{id}/confirm_continue
Changes:
- operation_above_limit: returned (instead of risk_declined) when the payment attempt count exceeds the configured limit per intent.
- validation_error: returned (instead of risk_declined) when device_id is not a valid UUID.
terminal_id in terminal_info (under both payment_method.card and payment_method.card_present) is renamed to terminal_identifier. The field represents the 8-digit alphanumeric identifier sent to the card scheme, not the Airwallex Terminal resource ID; the new name avoids that confusion.

Affected endpoints:
- /api/v1/pa/payment_intents/*
- /api/v1/pa/payment_attempts/*
Changes:
- payment_method.card.terminal_info.terminal_id: renamed to payment_method.card.terminal_info.terminal_identifier
- payment_method.card_present.terminal_info.terminal_id: renamed to payment_method.card_present.terminal_info.terminal_identifier
The payment_method.card.three_ds node is removed from API requests. payment_method.card.three_ds.return_url is replaced by the top-level return_url; all other fields in the node were already deprecated and unused.

Affected endpoints:
- POST /api/v1/pa/payment_intents/create
- POST /api/v1/pa/payment_intents/{id}/confirm
Changes:
- payment_method.card.three_ds: removed from the request (use top-level return_url).
Timestamp fields in responses now use the ISO-8601 standard timezone offset format +00:00 instead of the legacy +0000. For example, 2024-06-15T10:30:00+0000 is now returned as 2024-06-15T10:30:00+00:00. Date-only fields (YYYY-MM-DD) are unaffected.

Affected endpoints:
- All Payment Acceptance endpoints returning timestamp fields (e.g. created_at, updated_at).
The settlement id response field is renamed to settlement_id.

Affected endpoints:
- GET /api/v1/pa/financial/settlements
- GET /api/v1/pa/financial/settlements/{id}
- GET /api/v1/pa/financial/settlements/{id}/report
Changes:
- id: renamed to settlement_id in the settlement list, settlement retrieve, and settlement report responses.
The version query parameter is removed from the Get a settlement report endpoint, as the old version is deprecated. The report is always generated using the latest report version.

Affected endpoints:
- GET /api/v1/pa/financial/settlements/{id}/report
Changes:
- version: removed from the request query parameters.
The Get a settlement report by ID API gains a report_status field. If the report is available, report_status READY and a populated report_url is returned. Otherwise the report is generated with report_status IN_PROGRESS; report_url is populated once the report reaches READY.

Affected endpoints:
- GET /api/v1/pa/financial/settlements/{id}/report
Changes:
- report_status: added to the response. READY when the report is available; IN_PROGRESS while it is being generated.
- If the report is not yet available, it is generated; report_url is populated once report_status is READY.
The datetime filter query parameters on the List payment disputes endpoint now require a valid timezone-aware ISO 8601 value. Previously, a value that could not be parsed as ISO 8601 silently fell back to local datetime parsing, ignoring the timezone; such values are now rejected with a validation error.

Affected endpoints:
- GET /api/v1/pa/payment_disputes
Changes:
- from_due_at, to_due_at, from_updated_at, to_updated_at, from_created_at, to_created_at: an invalid datetime value now returns a validation error instead of falling back to local datetime parsing. Provide timezone-aware ISO 8601 values (e.g. 2026-01-27T14:30:00Z or 2026-01-27T14:30:00+08:00).
Introduced failure object under Transfers resource to provide transfer failure details

Affected endpoints:
- GET /api/v1/transfers (response only)
- GET /api/v1/transfers/{id} (response only)
- POST /api/v1/transfers/create (response only)
- POST /api/v1/transfers/{id}/confirm_funding (response only)
Changes:
- Replaced failure_reason and failure_type with a new failure object, which contains failure code, message, and details.
Introduced failure_details in the funding object under Transfers and Batch Transfers resources to provide funding failure details Affected endpoints:
- GET /api/v1/transfers (response only)
- GET /api/v1/transfers/{id} (response only)
- POST /api/v1/transfers/create (response only)
- POST /api/v1/transfers/{id}/confirm_funding (response only)
- GET /api/v1/batch_transfers (response only)
- GET /api/v1/batch_transfers/{id} (response only)
- POST /api/v1/transfers/{id}/add_items (response only)
- POST /api/v1/transfers/{id}/delete (response only)
- POST /api/v1/transfers/{id}/delete_items (response only)
- POST /api/v1/transfers/{id}/quote (response only)
- POST /api/v1/transfers/{id}/submit (response only)
- POST /api/v1/transfers/{id}/create (response only)
Changes:
- Replaced failure_reason with failure_details in the funding object.

2026-05-29

customer_data_collection.enabled is removed from Billing Checkout APIs. New enum fields customer_data_collection.tax_id and customer_data_collection.billing_address are added.

Affected endpoints:
- POST /api/v1/billing_checkouts/create
- GET /api/v1/billing_checkouts/{id}
- GET /api/v1/billing_checkouts
- POST /api/v1/billing_checkouts/{id}/update
- POST /api/v1/billing_checkouts/{id}/cancel
Changes:
- customer_data_collection.enabled: removed
- customer_data_collection.tax_id: added enum field (DISABLED, OPTIONAL_IF_SUPPORTED, REQUIRED_IF_SUPPORTED; Default: OPTIONAL_IF_SUPPORTED)
- customer_data_collection.billing_address: added enum field (AUTO, REQUIRED; Default: AUTO)

2026-02-27

Updated status of financial reports to indicate FAILED when report generation process had failed. This is distinct from the previous PENDING state, which now indicates that the report generation is still in progress.

Affected endpoints:
- GET /api/v1/finance/financial_reports (response only)
- GET /api/v1/finance/financial_report/{id} (response only)
- POST /api/v1/finance/financial_reports/create (response only)

2025-11-11

In this version, the meaning of the field external_id on the Payment Source resource has changed from referencing a Payment Consent ID to referencing a Payment Method ID.

Affected endpoints:
- POST /api/v1/payment_sources/create
- GET /api/v1/payment_sources/{id}
- GET /api/v1/payment_sources
- (Sandbox Only) POST /api/v1/simulation/billing/payment_sources/{id}/fail_next_autocharge
Changes:
- external_id accepts a Payment Method ID instead of a Payment Consent ID.

2025-09-30

This version includes major changes to the Account Capability resource, notably relating to the querying of available funding limit or Faster Direct Debit limit.
Introduced new parameters to allow querying for future funding limits and funding limits of specific mandate types.

Affected endpoints:
- GET /api/v1/account_capabilities/funding_limits, request and response
Changes:
- Added new effective_at field.
- Added new mandate_type field.
Updated response to include more details on funding limit.

Affected endpoints:
- GET /api/v1/account_capabilities/funding_limits, response only
Changes:
- Replaced the available field with an availables object. This object maps the key that is the direct debit scheme to the available funding limit for that scheme.
Renamed pagination parameters.

Affected endpoints:
- GET /api/v1/account_capabilities/funding_limits, request only
Changes:
- Renamed pageNum field to page_num.
- Renamed pageSize field to page_size.
Updated source and amount for balance activity where source_type is ISSUING:
- source: Change value from Retrieval Reference Number to Issuing transaction's transaction_id
- amount: Invert sign where transaction_type is ISSUING_AUTHORISATION_HOLD or ISSUING_AUTHORISATION_RELEASE to properly report on available balance changes
Affected endpoints:
- GET /api/v1/balance/history (response only)

2025-08-29

In this version, we introduce several improvements to the Billing APIs, including enhanced pagination, a new subscription duration parameter, and clearer representation of tiered invoice line items. We also add new features, such as:
- In Billing Checkout, support of collecting one-off payments; collecting and saving a payment method for future payments.
- Support of creating one-off invoices with existing payment sources and a simulation API to facilitate testing of payments.
- A new API to simulate auto-charge behavior in the sandbox environment.
Pagination update for search endpoints of Billing.

Affected endpoints for both request and response:
- GET /api/v1/billing_customers
- GET /api/v1/billing_transactions
- GET /api/v1/invoices
- GET /api/v1/invoices/{id}/line_items
- GET /api/v1/payment_sources
- GET /api/v1/prices
- GET /api/v1/products
- GET /api/v1/subscriptions
- GET /api/v1/subscriptions/{id}/items
- GET /api/v1/billing_checkouts
Changes:
- Replaced page_num with page in request payload.
- Replaced has_more with page_before and page_after in response payload.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis.
Subscription model and API updates: we have updated the representation of subscription duration to make it clearer and easier to use.

Affected endpoints:
- POST /api/v1/subscriptions/create (request and response)
- POST /api/v1/subscriptions/{id}/update (request and response)
- GET /api/v1/subscriptions/{id} (response only)
- GET /api/v1/subscriptions (response only)
- POST /api/v1/subscriptions/{id}/cancel (response only)
- POST /api/v1/invoices/preview (request only)
- POST /api/v1/billing_checkouts/create (request and response)
- GET /api/v1/billing_checkouts/{id} (response only)
- GET /api/v1/billing_checkouts (response only)
- POST /api/v1/billing_checkouts/{id}/update (response only)
- POST /api/v1/billing_checkouts/{id}/cancel (response only)
Changes:
- Removed total_billing_cycles and remaining_billing_cycles from the Subscription object, now replaced by duration.
- Replaced recurring and total_billing_cycles parameters with a single duration field in Create/Update Subscription requests, allowing developers to explicitly define the subscription length.
- Replaced total_billing_cycles with duration in the subscription_data of the Billing Checkout resource and corresponding create request.
- Renamed the cancel_at field to ends_at in the Subscription model.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis.
Introduce a new simulation API to simulate auto-charge behaviors in the sandbox environment.

New endpoint:
- POST /api/v1/simulation/billing/payment_sources/{id}/fail_next_autocharge
Changes:
- This API allows developers to simulate a failure of the next auto-charge attempt for a payment source. It is available only in the sandbox environment.
Introduced enhancements to Invoice APIs to support creating one-off invoices with automatic charging using existing Payment Sources.

Affected endpoints:
- POST /api/v1/invoices/create (request and response)
- POST /api/v1/invoices/{id}/update (request and response)
- GET /api/v1/invoices/{id} (response only)
- GET /api/v1/invoices (response only)
- POST /api/v1/invoices/{id}/finalize (response only)
- POST /api/v1/invoices/{id}/mark_as_paid (response only)
- POST /api/v1/invoices/{id}/void (response only)
- POST /api/v1/invoices/{id}/add_line_items (response only)
- POST /api/v1/invoices/{id}/update_line_items (response only)
- POST /api/v1/invoices/{id}/delete_line_items (response only)
Changes:
- Added a new enum value AUTO_CHARGE for the collection_method field.
- Added a new payment_source_id field to enable automatic charging with an existing Payment Source.
Improved Invoice Line Item APIs to provide more detailed price information.

Affected endpoints:
- GET /api/v1/invoices/{id}/line_items/{item_id} (response only)
- GET /api/v1/invoices/{id}/line_items (response only)
Changes:
- Added a label field to the Invoice Line Item object to indicate what the charge is for. This is especially useful for GRADUATED tiered prices, which may generate multiple Invoice Line Items.
Introduced PAYMENT mode and SETUP mode to Billing Checkout.
- PAYMENT mode: collect a one-off payment and generate an invoice.
- SETUP mode: collect and save a payment method for future use as a Payment Source.
Affected endpoints:
- POST /api/v1/billing_checkouts/create
- GET /api/v1/billing_checkouts/{id} (response only)
- GET /api/v1/billing_checkouts (response only)
- POST /api/v1/billing_checkouts/{id}/update (response only)
- POST /api/v1/billing_checkouts/{id}/cancel (response only)
Changes:
- Added a mode field to specify the intended outcome of the Billing Checkout: SUBSCRIPTION, PAYMENT, or SETUP.
- Added an invoice_id field to reference the invoice created upon completion in PAYMENT mode.
- Added an invoice_data object field to configure invoice creation settings when using PAYMENT mode.
Updated Subscription and Invoice webhooks (refer to webhook event types for more details)

2025-06-30

This version includes major changes to the Transfers resources, notably relating to the new scheduled transfer experience for the pre-funding settlement model, and an update to the beneficiary schema for US ACH transfers.
Introduced a new lock_rate_on_create field to denote whether to lock the conversion rate for a scheduled transfer upon creation.

Affected endpoints:
- POST /api/v1/transfers/create, request and response
- POST /api/v1/transfers/validate, request only
- GET /api/v1/transfers/{id}, response only
- GET /api/v1/transfers, response only
Changes:
- Added a boolean lock_rate_on_create field to denote whether to lock the conversion rate for a scheduled transfer. This field should only be specified when a conversion is involved. The value can be TRUE or FALSE. If not specified, the default value is TRUE.
- If TRUE: The transfer is created with a confirmed conversion rate and prepayment. Details are provided in the conversion and prepayment objects. The remaining transfer amount will be deducted on the transfer date.
- If FALSE: The transfer is created without a confirmed conversion rate, and no funds are deducted at creation. The conversion rate will be confirmed and funds will be deducted on the transfer date.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not available.
Introduced new conversion and prepayment objects.

Affected endpoints:
- POST /api/v1/transfers/create, response only
- GET /api/v1/transfers/{id}, response only
- GET /api/v1/transfers, response only
Changes:
- Added a new prepayment object with the following details of the scheduled transfer prepayment.
- amount: The prepayment amount to be paid.
- currency: The prepayment currency.
- Replaced conversion_id with conversion object, which contains the following details of the underlying conversion of a transfer.
- rate: The rate of the conversion.
- currency_pair: The currency pair of the conversion.
- From this API version onward, changes above will be available generally; for earlier API versions, changes above are not available.
Updated Transfer webhooks (refer to webhook payload examples for more details)
Introduced bank_account_category for US ACH transfers to specify bank account type.

Affected endpoints:
- POST /api/v1/beneficiaries/create, request and response
- POST /api/v1/beneficiaries/update/{id}, request and response
- POST /api/v1/beneficiaries/validate, request only
- POST /api/v1/beneficiary_api_schemas/generate, response only
- POST /api/v1/beneficiary_form_schemas/generate, response only
- POST /api/v1/transfers/create, request and response
- POST /api/v1/transfers/validate, request only
- POST /api/v1/transfers/{id}/confirm_funding, response only
- POST /api/v1/batch_transfers/{id}/add_items, request only
- GET /api/v1/beneficiaries, response only
- GET /api/v1/beneficiaries/{id}, response only
- GET /api/v1/transfers, response only
- GET /api/v1/transfers/{id}, response only
- GET /api/v1/batch_transfers/{id}/items, response only
Changes:
- Where bank_country_code is US, transfer_methods is LOCAL, local_clearing_system is ACH / NEXT_DAY_ACH and account_currency is USD:
  - bank_account_category is now required
Beneficiaries created using POST /api/v1/beneficiaries/create on a previous API version will be compatible with this version by defaulting to CHECKING without updating to the new schema. However, to update an existing beneficiary by calling POST /api/v1/beneficiaries/update/{beneficiary_id}, you will need to follow the new schema.
Introduced account_type under us_bank object to specify bank account type for US Linked Accounts

Affected endpoints:
- POST /api/v1/linked_accounts/create, request and response
- GET /api/v1/linked_accounts, response only
- GET /api/v1/linked_accounts/{id}, response only
- POST /api/v1/linked_accounts/{id}/verify_microdeposits, response only
Changes:
- Where type is US_BANK and preferred_verification_type is MICRO_DEPOSIT:
  - account_type is now required.
- US Linked Accounts created using POST /api/v1/linked_accounts/create on a previous API version will be compatible with this version by defaulting to CHECKING without updating to the new schema.

2025-06-16

This version includes major changes to Billing APIs via the following new resources:
- Billing Customers, Payment Sources, and Billing Transactions to better abstract the payment provider resources from the billing software resources.
- Billing Checkouts to create an Airwallex-hosted checkout page where customers can pay for items or save payment details for future use.
- Credit Notes to adjust the amount of a finalized invoice by refund.
Additionally, it introduces changes to the Subscriptions, Subscription Items, Invoices, and Invoice Items to provide enhanced features.
This version includes major changes to Billing APIs. It introduces new resources like Billing Customers, Payment Sources, and Billing Transactions to better abstract the payment provider resources from the billing software resources, and a new resources Billing Checkouts to create an Airwallex-hosted checkout page where customers can pay for items or save payment details for future use. Additionally, it introduces changes to the Subscriptions, Subscription Items, Invoices, and Invoice Items to provide enhanced features.
Introduced new Billing Customers resource – A new resource representing customers in Billing, separate from the Payment Acceptance customers. Billing Customers store customer data for billing purposes and link to invoices and subscriptions.

New endpoints:
- GET /api/v1/billing_customers
- POST /api/v1/billing_customers/create
- GET /api/v1/billing_customers/{id}
- POST /api/v1/billing_customers/{id}/update
Changes:
- Replaced the use of customer_id (Payment Acceptance Customer ID) with billing_customer_id across Billing API endpoints (e.g. in Subscriptions and Invoices APIs).
- Billing Customer ID is now required when creating subscriptions or invoices, and is used to filter results when listing these resources.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis.
Introduced Payment Source resource – A new resource for managing a customer’s saved funding source for billing. A Payment Source can be created from a verified payment consent and used for future charges in subscriptions or invoices.

New endpoints:
- GET /api/v1/payment_sources
- POST /api/v1/payment_sources/create
- GET /api/v1/payment_sources/{id}
Changes:
- Payment Sources replace the direct use of Payment Consents in the Billing API. For example, subscription creation now uses a Payment Source ID instead of a Payment Consent ID.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis.
Introduced Billing Transactions resource – A new read-only resource that records transactions related to invoices.

New endpoints:
- GET /api/v1/billing_transactions
- GET /api/v1/billing_transactions/{id}
Changes:
- Added the Billing Transactions list and retrieve endpoints. Each Billing Transaction represents a financial transaction on an invoice.
- Billing Transaction objects include details such as the related invoice ID, transaction amount, currency, type of transaction, and status (e.g. completed or pending).
- These endpoints are read-only; transactions are created by the system, for instance, when an invoice is paid.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis.
Introduced new Billing Checkouts resource – A new resource manages the setup and lifecycle of an Airwallex-hosted customer checkout experience, enabling customers to confirm and pay for line items or set up payment details for future transactions.

New endpoints:
- POST /api/v1/billing_checkouts/create
- GET /api/v1/billing_checkouts/{id}
- GET /api/v1/billing_checkouts
- POST /api/v1/billing_checkouts/{id}/update
- POST /api/v1/billing_checkouts/{id}/cancel
Subscription API updates (collection methods and scheduling) – The Subscription endpoints have been enhanced to support multiple collection methods and flexible start times.

Affected endpoints:
- GET /api/v1/subscriptions (request and response)
- POST /api/v1/subscriptions/create (request and response)
- GET /api/v1/subscriptions/{id} (response only)
- POST /api/v1/subscriptions/{id}/update (request and response)
- GET /api/v1/subscriptions/{id}/items/{item_id} (response only)
- GET /api/v1/subscriptions/{id}/items (response only)
Changes:
- Added a few new fields to Subscription resource and endpoint requests correspondingly:
  - Added a new required field collection_method to specify how payments are collected. Supported values: AUTO_CHARGE (automatically charge a saved Payment Source each cycle), CHARGE_ON_CHECKOUT (generate an invoice for manual payment via hosted invoice page), or OUT_OF_BAND (payments handled outside of Airwallex).
  - Introduced billing_customer_id in place of the old customer identifier. All subscriptions must reference a Billing Customer ID (see new Billing Customers resource).
  - Introduced payment_source_id (required when collection_method=AUTO_CHARGE) to indicate which Payment Source to charge every billing cycle (this replaces the previous payment_consent_id field). For manual invoice collection, added linked_payment_account_id (required when collection_method=CHARGE_ON_CHECKOUT) to specify which account will be used as payment account.
  - Added optional fields days_until_due (grace period from invoice issuance to due date, for manual payments; defaults to 0), default_tax_percent (default tax rate to apply to generated invoices), and default_invoice_template (to specify settings for generated invoices). These allow configuring invoice payment terms and appearance per subscription.
  - Added starts_at to allow scheduling a subscription to begin at a future date/time. A subscription created with a future start time will now be in a new PENDING status until it commences (or until a trial starts).
  - Introduced a new PENDING subscription status (for not-yet-started subscriptions). The overall subscription status lifecycle remains the same for trials and payment failures (IN_TRIAL, ACTIVE, UNPAID, CANCELLED), with the addition of PENDING as a preliminary status.
  - Renamed some fields
    - current_period_start_at renamed to current_period_starts_at.
    - current_period_end_at renamed to current_period_ends_at.
    - trial_start_at renamed to trial_starts_at.
    - trial_end_at renamed to trial_ends_at.
  - Removed request_id from the Subscription resource in the API responses.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis.
Invoice API enhancements (one-off invoices & payment status) – You can now create invoices that are not generated from subscriptions (true one-off invoices), run them through a draft to finalise lifecycle, and your customer can pay online when the collection method is CHARGE_ON_CHECKOUT. Invoice Item resource is now renamed to Invoice Line Item, and users can now add, update, or remove multiple line items on a draft one-off invoice through dedicated endpoints.

New endpoints:
- POST /api/v1/invoices/create
- POST /api/v1/invoices/{id}/update
- POST /api/v1/invoices/{id}/finalize
- POST /api/v1/invoices/{id}/void
- POST /api/v1/invoices/{id}/delete
- POST /api/v1/invoices/{id}/mark_as_paid
- GET /api/v1/invoices/{id}/line_items/{invoice_line_item_id}
- GET /api/v1/invoices/{id}/line_items
- POST /api/v1/invoices/{id}/add_line_items
- POST /api/v1/invoices/{id}/update_line_items
- POST /api/v1/invoices/{id}/delete_line_items
Removed endpoints:
- GET /api/v1/invoices/{id}/items/{item_id}
- GET /api/v1/invoices/{id}/items
Affected endpoints:
- GET /api/v1/invoices (request and response)
- GET /api/v1/invoices/{id} (response only)
- POST /api/v1/invoices/preview (request and response)
Changes:
- Invoices can now be created via API in a DRAFT state (using the new create endpoint). A draft invoice can be edited and must be explicitly finalized to issue the invoice. Once finalized, the invoice status changes to FINALIZED (which replaces the previous “Sent” concept).
- You can now add, update, or remove multiple line items on a DRAFT state one-off invoice through Invoice Line Item endpoints.
- It is now possible to delete an invoice that is in DRAFT status. Deleting a draft removes the invoice record; this operation is only allowed for invoices that have not been finalized.
- Introduced an endpoint to cancel a finalized invoice. A voided invoice moves to a VOIDED status, indicating it has been canceled and will not be collected.
- The invoice object now has a refined status field and a new payment_status field. Invoice status may be DRAFT, FINALIZED, or VOIDED. The payment_status field indicates whether the invoice has been paid, with possible values UNPAID or PAID. (An invoice that was formerly classified as “PAYMENT_FAILED” will now remain FINALIZED with payment_status=UNPAID after all payment attempts.)
- The query parameter customer_id for listing invoices has been replaced with billing_customer_id. Additionally, the list/filter API for invoices now accepts a status filter (using the new status values) and a payment_status filter. The old invoice status values SENT and PAYMENT_FAILED are no longer used; instead, clients should rely on the new status and payment_status fields.
- Removed period_start_at and period_end_at on Invoice resource.
- Added new fields to Invoice resource for new features:
  - Added legal_entity_id, collection_method, payment_source_id, linked_account_id, paid_out_of_band to Invoice resource for indicating payment information.
  - Added hosted_url, pdf_url to provide urls for hosted online payment and PDF download.
  - Added number and memo to indicate the invoice number and memo.
  - Added paid_at, finalized_at, voided_at, due_at, days_until_due to indicate times of operation or events.
  - Added days_until_due to support a delay between finalizing invoice and due.
  - Added total_tax_amount.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis.
Introduced new Credit Notes resource – A new resource for issuing refunds for returned goods, correcting pricing or quantity errors, and handling overpayments or other discrepancies of a finalized invoice.

New endpoints:
- POST /api/v1/credit_notes/create
- GET /api/v1/credit_notes/{id}
- GET /api/v1/credit_notes
- POST /api/v1/credit_notes/{id}/update
- POST /api/v1/credit_notes/{id}/finalize
- POST /api/v1/credit_notes/{id}/delete
- POST /api/v1/credit_notes/{id}/void
Introduced new Credit Note Line Items resource – A new resource for managing line items within credit notes. Credit note line items can be linked to invoice line items or be created independently.

New endpoints:
- GET /api/v1/credit_notes/{id}/line_items/{line_item_id}
- GET /api/v1/credit_notes/{id}/line_items
- POST /api/v1/credit_notes/{id}/add_line_items
- POST /api/v1/credit_notes/{id}/update_line_items
- POST /api/v1/credit_notes/{id}/delete_line_items
Pricing model updates – The Price resource has new billing attributes and updated pricing model options.

Affected endpoints:
- GET /api/v1/prices (response only)
- POST /api/v1/prices/create (request and response)
- GET /api/v1/prices/{id} (response only)
- POST /api/v1/prices/{id}/update (request and response)
Changes:
- Added a new field billing_type for recurring prices, indicating when the price is billed. Allowed values are IN_ADVANCE (bill at the start of each billing cycle) or IN_ARREARS (bill at the end of the cycle). This field appears in Price responses and can be set for recurring prices.
- Updated the pricing_model enumeration to PER_UNIT, FLAT, GRADUATED, and VOLUME. The previously used model names per_unit, volume, tiered and stairstep have been deprecated and consolidated under these new models.
- Added flat_amount as a field for FLAT pricing (specifies the flat charge amount). The field unit_amount remains for per-unit pricing and is now explicitly applicable only to PER_UNIT models. Both flat_amount and unit_amount are optional or required depending on the chosen pricing model.
- Added created_at and updated_at fields to indicate creation and last updated time.
- Removed request_id from the Price resource in the endpoint responses, and removed request_id from the request of Update Price endpoint.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis.
Product update

Affected endpoints:
- POST /api/v1/products/create (response only)
- GET /api/v1/products/{id} (response only)
- POST /api/v1/products/{id}/update (response only)
- GET /api/v1/products (response only)
Changes:
- Added created_at and updated_at fields to indicate creation and last updated time.
- Removed request_id from the Product resource in the API responses, and removed request_id from the request of update Product endpoint.
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis.
Billing webhooks are updated based on the new life cycle of resources.
- Added new webhook events:
  - invoice.created
  - invoice.finalized
  - invoice.voided
  - invoice.payment.paid
  - subscription.in_trial
  - subscription.active
  - subscription.unpaid
  - subscription.modified
  - billing_transaction.created
  - billing_transaction.succeeded
  - billing_transaction.cancelled
  - billing_checkout.created
  - billing_checkout.cancelled
  - billing_checkout.completed
  - credit_note.created
  - credit_note.finalized
  - credit_note.voided
- Deprecated webhook events:
  - invoice.sent
  - invoice.paid
  - invoice.payment_failed
  - invoice.payment_attempt_failed
  - subscription.updated

2025-04-25

This version includes major changes to the Transfers, Beneficiaries, Global Accounts, and Deposits resources. The previously beta-released Wallet Transfers resource has been deprecated and replaced by the unified Transfers resource, which now supports both bank and wallet transfers.
Introduced a new Digital Wallet beneficiary type to Transfers and Beneficiaries under Payouts.

Affected endpoints:
- POST /api/v1/transfers/create, request and response
- POST /api/v1/transfers/validate, request only
- GET /api/v1/transfers/{id}, response only
- GET /api/v1/transfers, response only
- GET /api/v1/beneficiaries, request and response
- GET /api/v1/beneficiaries/{id}, response only
- POST /api/v1/beneficiaries/create, request and response
- POST /api/v1/beneficiaries/{id}/update, request and response
- POST /api/v1/beneficiaries/validate, request only
Changes:
- Added a new field type under the beneficiary object, with possible values of BANK_ACCOUNT or DIGITAL_WALLET
- Added a new nested digital_wallet object within the beneficiary object when the beneficiary type is Digital Wallet. Required fields are as follows:
- account_name: account holder name of the beneficiary’s digital wallet
- id_type: account identifier type of the beneficiary’s digital wallet
- id_value: account identifier value of the beneficiary’s digital wallet
- provider: service provider of the beneficiary's digital wallet
Updated parameters according to Bank Account and Digital Wallet beneficiary types.

Affected endpoints:
- POST /api/v1/beneficiary_api_schemas/generate, request and response
- POST /api/v1/beneficiary_form_schemas/generate, request and response
Changes:
- Added type to Bank Account request parameters
- Added provider and type to Digital Wallet request parameters
- Newly added parameters are also returned in the condition object in the response
Introduced a new interim status for in-progress Global Account creations to Global Accounts under Core Resources.

Affected endpoints:
- GET /api/v1/global_accounts, response only
- GET /api/v1/global_accounts/{id}, response only
- POST /api/v1/global_accounts/{id}/close, response only
- POST /api/v1/global_accounts/{id}/update, response only
- POST /api/v1/global_accounts/create, response only
Changes:
- Added PROCESSING under status in response body. Subscribe to Global Account status webhooks for subsequent changes
Introduced a new reason field for failed Global Account creations.

Affected endpoints:
- GET /api/v1/global_accounts, response only
- GET /api/v1/global_accounts/{id}, response only
- POST /api/v1/global_accounts/{id}/update, response only
Changes:
- Added failure_reason to response body
- Updated INACTIVE to FAILED in response body
Introduced and updated reason fields for closed Global Accounts.

Affected endpoints:
- GET /api/v1/global_accounts, response only
- GET /api/v1/global_accounts/{id}, response only
- POST /api/v1/global_accounts/{id}/close, response only
- POST /api/v1/global_accounts/{id}/update, response only
Changes:
- Added new close_reason for closures initiated by the financial institution.
- Updated descriptions and recommended next steps for other close_reason values.
Added new webhook events.
- global_account.active
- global_account.closed
- global_account.failed
Deprecated webhook event.
- ga.new
Introduced new Digital Wallet Transfer deposit type and Aggregate Funds deposit type to Deposits under Core Resources.

Affected endpoint:
- GET /api/v1/deposits/{id}, response only
- GET /api/v1/deposits, response only
Changes:
- Added new type of DIGITAL_WALLET_TRANSFER and AGGREGATE_FUNDS
- Added a new nested digital_wallet object within the payer object when the deposit type is DIGITAL_WALLET_TRANSFER or AGGREGATE_FUNDS with the following fields:
- account_name: account name of the payer’s digital wallet
- id_type: account identifier type of the payer’s digital wallet
- id_value: account identifier value of the payer’s digital wallet
- provider: service provider of the payer’s digital wallet
Introduced a new Get supported financial institutions API endpoint to return supported beneficiary financial institutions for a provided transfer method.

New endpoint:
- POST /api/v1/beneficiary_api_schemas/supported_financial_institutions
Changes:
- From this API version onward, this endpoint will be available generally. See details in this endpoint’s specifications below
- For earlier API versions, this feature is not enabled by default. Access is provided on a request basis
Updated the UI definitions in the form schema for bank-code-type fields (e.g., account_routing_value1, swift_code) under beneficiary bank details.

Affected endpoint:
- POST /api/v1/beneficiary_api_schemas/generate, response only
Changes:
- For bank-code-type fields, the type attribute has been updated from "INPUT" to "SELECT" or "DYNAMIC_SELECT" to suggest a dropdown UI element to select a bank
- When the type is "SELECT", an array of labels and values will be returned under options
- When the type is "DYNAMIC_SELECT", the full bank list cannot be retrieved all at once, and a set of API definitions and request parameters will be returned under dynamic_options, suggesting leveraging the Get supported financial institutions API to render the bank list. The following attributes will be included in this object:
  - query_params: An array of request parameters to use in the new API endpoint with definitions
  - query_params.name: The key of the request parameter in the new API endpoint
  - query_params.pattern: Format requirement in regular expression
  - query_params.value_of: The path to a field in this current API
  - query_url: Relative URL of the new API endpoint
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis
Added a new dispatch_info object under the Transfers resource. Only available for some transfer methods after the transfer is created.

Affected endpoints:
- GET /api/v1/transfers/{id}, response only
- GET /api/v1/transfers, response only
Changes:
- dispatch_info will be populated in the transfer resource and the webhook event bodies when available. The following fields will be included:
  - external_reference: A reference ID to track a transfer after it's dispatched from Airwallex
  - external_reference_type: The definition of the external_reference in the payment system
- From this API version onward, changes above will be available generally; for earlier API versions, this feature is not enabled by default. Access is provided on a request basis
Updated Transfer and Deposit webhooks (refer to webhook event types for more details)
Update transfer error code request_id_duplicate to duplicate_request_id in alignment with the latest Airwallex API convention

2025-02-14

Renamed the status SUCCEEDED to SETTLED under Refund.

Affected endpoints:
- GET /api/v1/pa/refunds request and response
- POST /api/v1/pa/refunds/create response only
- GET /api/v1/pa/refunds/{id} response only
Affected Webhook:
- Renamed refund.succeeded to refund.settled
Moved channel specific data to a unified additional_info field under PaymentIntent.

Affected endpoints:
- POST /api/v1/pa/payment_intents/create request and response
- GET /api/v1/pa/payment_intents/{id} response only
- POST /api/v1/pa/payment_intents/{id}/update request and response
- POST /api/v1/pa/payment_intents/{id}/confirm response only
- POST /api/v1/pa/payment_intents/{id}/confirm_continue response only
- POST /api/v1/pa/payment_intents/{id}/capture response only
- POST /api/v1/pa/payment_intents/{id}/cancel response only
- GET /api/v1/pa/payment_intents response only
Changes:
- Moved fields from additional_info under Customer to unified additional_info under PaymentIntent
- Removed travelers, itineraries under order
Removed deprecated fields from API requests.

Affected endpoints:
- POST /api/v1/pa/payment_intents/create
- POST /api/v1/pa/payment_consents/{id}/verify
Changes:
- Removed payment_method_options.card.risk_control from PaymentIntent Create Request
- Removed verification_options.card.risk_control from PaymentConsent Verify Request
Removed deprecated fields from API responses.

Affected endpoints:
- GET /api/v1/pa/payment_intents*
- POST /api/v1/pa/payment_intents/*
Changes:
- Removed deprecated fields from PaymentIntent:
  - payment_method_options.card.risk_control
  - business_info.postcode
  - order.supplier
Enhanced AVS result in API responses.

Affected endpoints:
- GET /api/v1/pa/customers*
- GET /api/v1/pa/payment_attempts*
- GET /api/v1/pa/payment_consents*
- POST/api/v1/pa/payment_consents/
- GET /api/v1/pa/payment_intents*
- POST /api/v1/pa/payment_intents/{id}/cancel
- POST /api/v1/pa/payment_intents/{id}/capture
- POST /api/v1/pa/payment_intents/{id}/confirm_continue
- POST /api/v1/pa/payment_intents/{id}/confirm
- POST /api/v1/pa/payment_intents/{id}/update
- GET /api/v1/pa/payment_methods*
- POST /api/v1/pa/payment_methods/*
Changes:
- Removed two fields card.avs_check and card.cvc_check from PaymentMethod
- Updated return values of two data fields in PaymentAttempt:
  - authentication_data.avs_result: Y/N/U to fully_matched/partially_matched/unmatched/no_response/not_attempted
  - authentication_data.cvc_result: Y/N/U to matched/unmatched/no_response/not_attempted

2024-09-27

This version introduces major changes to the Payments, Batch Transfers, Beneficiaries, and Transfers resources, notably relating to the renaming of the resources, as well as related endpoints, fields, error codes, and webhook events.

Affected endpoints:
- POST /api/v1/payments/create → POST /api/v1/transfers/create
- POST /api/v1/payments/validate → POST /api/v1/transfers/validate
- POST /api/v1/payments/{id}/cancel → POST /api/v1/transfers/{id}/cancel
- POST /api/v1/payments/{id}/confirm_funding → POST /api/v1/transfers/{id}/confirm_funding
- GET /api/v1/payments/{id} → GET /api/v1/transfers/{id}
- GET /api/v1/payments → GET /api/v1/transfers
- POST /api/v1/beneficiaries/update/{id} → POST /api/v1/beneficiaries/{id}/update
- POST /api/v1/beneficiaries/delete/{id} → POST /api/v1/beneficiaries/{id}/delete
- POST /api/v1/transfers/create → POST /api/v1/connected_account_transfers/create
- GET /api/v1/transfers/{id} → GET /api/v1/connected_account_transfers/{id}
- GET /api/v1/transfers → GET /api/v1/connected_account_transfers
Changes:
- Renamed "payments" to "transfers" in endpoint URL paths for Transfers resource, previously known as Payments resource in legacy API versions
- Renamed "transfer" to "connected_account_transfer" in endpoint URL paths for Connected Account Transfers resource, previously known as Transfers resource in legacy API versions
Modified field namings in requests and responses.

Affected endpoints:
- POST /api/v1/transfers/create
- POST /api/v1/transfers/validate
- POST /api/v1/transfers/{id}/cancel
- POST /api/v1/transfers/{id}/confirm_funding
- GET /api/v1/transfers/{id}
- GET /api/v1/transfers
- POST /api/v1/batch_transfers/create
- GET /api/v1/batch_transfers/{id}
- GET /api/v1/batch_transfers
- POST /api/v1/batch_transfers/{id}/quote
- POST /api/v1/batch_transfers/{id}/submit
- POST /api/v1/batch_transfers/{id}/delete
- POST /api/v1/batch_transfers/{id}/add_items
- POST /api/v1/batch_transfers/{id}/delete_items
- GET /api/v1/batch_transfers/{id}/items
- GET /api/v1/beneficiaries
- GET /api/v1/beneficiaries/{id}
- POST /api/v1/beneficiaries/create
- POST /api/v1/beneficiaries/{id}/update
- POST /api/v1/beneficiaries/{id}/delete
- POST /api/v1/beneficiaries/validate
- POST /api/v1/beneficiary_api_schemas/generate
- POST /api/v1/beneficiary_form_schemas/generate
- POST /api/v1/simulation/transfers/{id}/transition
Changes:
- Renamed fields in requests and responses of Transfers endpoints
  - payment_id → id
  - payment_amount → transfer_amount
  - payment_currency → transfer_currency
  - underlying_conversion_id → conversion_id
  - payment_date → transfer_date
  - payment_method → transfer_method
  - last_updated_at → updated_at
- Renamed fields in requests and responses of Batch Transfers endpoints
  - payment_amount → transfer_amount
  - payment_currency → transfer_currency
  - payment_date → transfer_date
  - payment_method → transfer_method
- Renamed fields in requests and responses of Beneficiaries endpoints
  - beneficiary_id → id
  - payment_methods → transfer_methods
  - payment_reason → transfer_reason
- Renamed fields in requests and responses of Payers endpoints
  - payer_id → id
Modified pagination to align with the latest Airwallex API convention

Affected endpoint:
- GET /api/v1/transfers
Changes:
- Replaced page_num with page on request payload
- Replaced has_more with page_before and page_after on response payload
Updated Transfer, Batch Transfer, and Connected Account Transfer webhooks (refer to webhook event types for more details)
Updated Transfer, Batch Transfer, Beneficiary, and Payer error code format (refer to transfer error codes and batch transfer error codes for more details)
Supported HTTP status code 409 (Conflict) if a request with the same request_id is currently being processed

Affected endpoint:
- POST /api/v1/transfers/create

2024-08-07

Introduced new versions of the Transaction Reconciliation Report and Balance Activity Report . The new version 1.1.0 will be the default report_version for these reports.

Affected endpoints:
- POST /api/v1/finance/financial_reports/create, request and response
Changes:
- The default report version for the BALANCE_ACTIVITY_REPORT and TRANSACTION_RECON_REPORT financial report types was changed to 1.1.0.
Modified request and response for create and get financial report(s) endpoints.

Affected endpoints:
- POST /api/v1/finance/financial_reports/create, request and response
- GET /api/v1/finance/financial_reports/{id}, response
- GET /api/v1/finance/financial_reports/, response
Changes:
- Renamed fields on the create financial report request payload
  - timezone to time_zone
  - from_created_at to from_date
  - to_created_at to date
- Renamed fields on the create and get financial report(s) response payloads
  - report_parameters.from_created_at to report_parameters.from_date
  - report_parameters.to_created_at to report_parameters.to_date
Modified responses for Financial Transactions resources.

Affected endpoints:
- GET /api/v1/financial_transactions, response
- GET /api/v1/financial_transactions/{id}, response
Changes:
- Update currency_pair value to align with standard FX currency pair conventions
- For payouts created after 2024-11-21, payout fees will now appear as separate line items to respective payouts
- Payouts for which the source currency and the payment currency are different will no longer generate CONVERSION_SELL and CONVERSION_BUY financial transactions records
Modified response for Get balance history endpoint.

Affected endpoints:
- GET /api/v1/balances/history, response
Changes:
- For payouts created after 2024-11-21, payout fees will now appear as separate line items to respective payouts
This version introduces major changes to the Global Accounts resource, notably relating to the opening and querying of Global Accounts due to:
Introduction of Multi-currency Global Accounts which can now receive funds in multiple currencies
Alignment to latest Airwallex API convention on pagination and URL naming

Affected endpoint:
- POST /api/v1/global_accounts/create request only
Changes:
- Renamed payment_methods to transfer_method
- Moved currency and transfer_method under a new required_features object
Affected endpoints:
- POST /api/v1/global_accounts/create response only
- GET /api/v1/global_accounts response only
- GET /api/v1/global_accounts/{id} response only
- POST /api/v1/global_accounts/{id}/close response only
- POST /api/v1/global_accounts/{id}/update response only
Changes:
- Renamed payment_methods to transfer_method
- Renamed clearing_system to local_clearing_system
- Removed capability object and moved transfer_methods and local_clearing_system under a new supported_features object, together with currency and routing_codes
- Replaced support_direct_debit by new type field under new supported_features object
- Added required_features object containing currency and transfer_method
Affected endpoint:
- GET /api/v1/global_accounts
Changes:
- Replaced page_num with page on request payload
- Renamed currency to supported_features.currency on request payload
- Added required_features.currency to request payload
- Replaced has_more with page_before and page_after on response payload
Update existing Global Account endpoint URL updated from POST /api/v1/global_accounts/update/{id}

Affected endpoint:
- POST /api/v1/global_accounts/{id}/update
This version also introduces major changes to the Deposits resource, notably relating to the responses and webhooks of deposits to include additional details such as remitter and fee information

Affected endpoints (Refer to direct debit for more details)
- GET /api/v1/deposits response only
- GET /api/v1/deposits/{id} response only
Changes:
- Renamed payer_name to name under new payer object, containing additional deposit information:
  - bank_account object added which details payer bank account information
  - country_code added
- Added provider_transaction_id to response body
- Added fee object to response body
  - amount added
  - currency added
- Removed source object from response body, moving funding_source_id and global_account_id directly under items
- Renamed deposit_id to id in response body
- Renamed estimated_settlement_time to estimated_settled_at in response body
- Renamed statement_ref to reference in response body
- Note that additional fields in the response are conditional based on the type of deposit and the data available from our banking partners. For example, the payer object is now only included for bank transfer deposits, but not for direct debit deposits (Refer to response body for more details)
Deposits webhook events now cover bank transfer deposits in addition to direct debit deposits, distinguished by modified type field to be either BANK_TRANSFER or, DIRECT_DEBIT
Added new deposit.pending webhook event

Affected webhook events (Refer to webhook event types for more details)
- deposit.settled
- deposit.rejected
- deposit.reversed
Payload Changes:
- Added data object that includes all enriched details retrieved from GET /api/v1/deposits endpoints
This version also introduces major changes to the Transfers and Batch Transfers resource, notably relating to the responses and webhooks of transfers to include application fees for Platform Revenue Control.

Affected endpoints:
- POST /api/v1/transfers/create, request and response
- GET /api/v1/transfers/{id}, response only
- GET /api/v1/transfers, response only
- POST /api/v1/batch_transfers/{{batch_id}}/add_items, request and response
- GET /api/v1/batch_transfers/{{batch_id}}/items, response only
Changes:
- Added application_fee_options to request payload
- Added application_fee_options to response payload
- Added application_fees to response payload

2024-06-30

Replaced Retrieve an indicative MarketFX quote with Retrieve an indicative rate.

Affected endpoints:
- GET /api/v1/marketfx/quote, removed
Replaced with:
- GET /api/v1/fx/rates/current
Replaced Create a LockFX quote with Create a quote.

Affected endpoints:
- POST /api/v1/lockfx/create, removed
Replaced with:
- POST /api/v1/fx/quotes/create
Modified request and response for conversion create and get endpoints.

Affected endpoints:
- POST /api/v1/fx/conversions/create, request and response
- GET /api/v1/fx/conversions/{conversion_id}, response only
- GET /api/v1/fx/conversions, response only
Changes:
- Removed reason from request payload
- Removed term_agreement from request payload
- Added application_fee_options to request payload
- Added funding_source to request payload
- Added metadata to request payload
- Renamed last_updated_at to updated_at from response payload
- Renamed settlement_cutoff_time to settlement_cutoff_at from response payload
- Added application_fee_options to response payload
- Added application_fees to response payload
- Added funding_source to response payload
- Added funding to response payload

2024-06-14

Modified the next_action payload of card confirm response.

Affected endpoints:
- POST /api/v1/pa/payment_intents/{id}/confirm, response only
Changes:
- Removed stage from next_action.
Modified the three_ds and type payload of card confirm_continue request.

Affected endpoints:
- POST /api/v1/pa/payment_intents/{id}/confirm_continue, request only
Changes:
- Removed three_ds from request payload
- Removed 3ds_continue, 3ds_check_enrollment, 3ds_validate from type.

2024-04-30

This version introduces major changes to the Payments and Beneficiaries resources, notably relating to the payment status lifecycle (including corresponding API endpoints/webhook events), and required fields for the beneficiary object.
Added PAID to payout statuses beyond SENT for better visibility after it has been dispatched by Airwallex for the following endpoints (refer to payout statuses for details):
- GET /api/v1/payments, response only
- GET /api/v1/payments/{payment_id}, response only
- POST /api/v1/payments/create, response only
Updated payment webhooks (refer to payout webhook for details).
- Add payment.paid
For both beneficiaries and payments endpoints, beneficiary name and address parameters are no longer relevant for certain payout scenarios (see detailed conditions below). Impacted endpoints:
- POST /api/v1/beneficiaries/create
- POST /api/v1/beneficiaries/update/{id}
- POST /api/v1/beneficiaries/validate
- POST /api/v1/payments/create
- POST /api/v1/payments/validate
- POST /api/v1/payments/retry/{id}
- GET /api/v1/beneficiaries
- GET /api/v1/beneficiaries/{id}
- GET /api/v1/payments
- GET /api/v1/payments/{id}
- POST /api/v1/beneficiary_form_schemas/generate
- POST /api/v1/batch_transfers/{id}/add_items
When a parameter is not relevant, values specified in requests will be ignored, and NOT validated, saved, or returned. For existing resources created with names and addresses under previous API versions:
Under this and all future API versions, beneficiary names and addresses under the conditions defined above will NOT be returned in any responses or modifiable through the beneficiaries/update endpoint, since they have become irrelevant.
Under all previous API versions except 2017-01-01, these parameters (as defined above) will be Optional, and are still validated, saved, and returned as before.

Changes:
- For ALL beneficiaries and payments except for US Paper Checks , the following parameters will NOT be relevant in requests nor returned in responses:
  - beneficiary.first_name
  - beneficiary.last_name
  - beneficiary.company_name
For domestic payout scenarios in which the beneficiary bank_country_code is the same as the onboarding entity country/region, the following beneficiary address parameters will NOT be relevant for requests nor returned in responses:
- beneficiary.address.country_code
- beneficiary.address.state
- beneficiary.address.city
- beneficiary.address.street_address
- beneficiary.address.postcode
Applicable scenarios by onboarding entity are as follows:
- Airwallex Hong Kong
  - beneficiary.bank_details.bank_country_code = HK
  - beneficiary.bank_details.account_currency = HKD or CNY
  - payment_method = LOCAL
  - beneficiary.bank_details.local_clearing_system = FPS or ACH
- Airwallex Australia
  - beneficiary.bank_details.bank_country_code = AU
  - beneficiary.bank_details.account_currency = AUD
  - payment_method = LOCAL
- Airwallex Lithuania/Netherlands
  - beneficiary.bank_details.bank_country_code is one of AT,BE,BG,CH,CY,CZ,DE,DK,EE,ES,FI,FR,GB,GR,HR,HU,IE,IS,IT,LI,LT,LU,LV,MC,MQ,MT,NL,NO,PL,PM,PT,RO,SE,SI,SK,SM,YT
  - beneficiary.bank_details.account_currency = EUR
  - payment_method = LOCAL
- Airwallex New Zealand
  - beneficiary.bank_details.bank_country_code = NZ
  - beneficiary.bank_details.account_currency = NZD
  - payment_method = LOCAL
- Airwallex Singapore
  - beneficiary.bank_details.bank_country_code = SG
  - beneficiary.bank_details.account_currency = SGD
  - payment_method = LOCAL
  - beneficiary.bank_details.local_clearing_system = FAST or GIRO
- Airwallex UK
  - beneficiary.bank_details.bank_country_code = GB
  - beneficiary.bank_details.account_currency = GBP
  - payment_method = LOCAL
  - beneficiary.bank_details.local_clearing_system = FASTER_PAYMENTS
- Airwallex US (does not apply to the MTL licensing model; please check with your Account Manager or Customer Service for eligibility)
  - beneficiary.bank_details.bank_country_code = US
  - beneficiary.bank_details.account_currency = USD
  - payment_method = LOCAL
  - beneficiary.bank_details.local_clearing_system = ACH
- For other customers onboarded with Airwallex's other entities, the address requirements remain the same

2024-04-04

Exposed new failed card transactions with transaction failure reasons through the Issuing Transactions APIs.
Updated the names of some existing card transaction failure reasons for clarity.

Affected endpoints:
- GET /api/v1/issuing/transactions, response only
- GET /api/v1/issuing/transactions/{id}, response only

Refer to transaction failure reasons for details

2024-03-31

Please note, this API version is incompatible with any Airwallex Business Account Products such as "Borderless Cards" or "Expense Management" via Airwallex web or mobile applications. If you're using any of these products, please use API version 2024-02-22. Contact your account manager for more information and to verify compatibility.
Revamps the Card and Cardholder experience.

Affected endpoints:
- POST /api/v1/issuing/cardholders/create, request and response
- GET /api/v1/issuing/cardholders, response only
- GET /api/v1/issuing/cardholders/{id}, response only
- POST /api/v1/issuing/cardholders/{id}/update, request and response
- POST /api/v1/issuing/cards/create, request and response
- GET /api/v1/issuing/cards/{id}, response only
- POST /api/v1/issuing/cards/{id}/update, request and response
- GET /api/v1/issuing/cards, response only
Changes:
- Added type cardholder attribute, valid values are DELEGATE and INDIVIDUAL
- Moved cardholder attribute address into individual object
- Added card attributes brand, program (an object containing purpose, type and sub_type), is_personalized and additional_cardholder_ids
- Removed card attribute issue_to
- Removed card attribute type

2024-02-22

With a subscribed webhook version greater than or equal to 2024-02-22, the naming convention of all webhook payloads will be unified as snake_case.
Renamed payment method flows and modified the next_action payloads.

Affected endpoints:
- POST /api/v1/pa/payment_consents/{id}/verify, request and response
- POST /api/v1/pa/payment_intents/{id}/confirm, request and response
- POST /api/v1/pa/payment_intents/*, response only
- GET /api/v1/pa/payment_intents*, response only
- GET /api/v1/pa/payment_attempts*, response only
Changes:
- Renamed payment method flows for the following payment methods: alipaycn, alipayhk, dana, tng, gcash, truemoney, rabbit_line_pay, kakaopay, wechatpay
- mweb to mobile_web
- inapp to mobile_app
- webqr to qrcode
- jsapi to official_account(applicable to wechatpay only)
- miniprog to mini_program
- Modified next_action from redirect to render_qrcode for the qrcode flow. Affected payment methods: alipaycn, alipayhk, dana, tng, gcash, truemoney, rabbit_line_pay, kakaopay
Split the Payment Consent status from PENDING_VERIFICATION to REQUIRES_PAYMENT_METHOD and REQUIRES_CUSTOMER_ACTION.

Affected endpoints:
- POST /api/v1/pa/payment_consents/*, response only
- GET /api/v1/pa/payment_consents*, response only
Added webhooks for the Payment Consent resource:
- payment_consent.requires_payment_method
- payment_consent.requires_customer_action
Reorganized fields under payment_method and payment_method_options.

Affected endpoints:
- POST /api/v1/pa/payment_intents/{id}/confirm, request only
Changes:
- Replaced payment_consent_reference.id with payment_consent_id
- Moved cvc from payment_consent_reference to payment_method.card
- Moved cryptogram, three_ds, external_three_ds from payment_method_options.card to payment_method.card
- Moved verification_method from payment_method_options.*_direct_debit to payment_method.*_direct_debit
Reorganized fields under payment_method and verification_options.

Affected endpoints:
- POST /api/v1/pa/payment_consents/{id}/verify, request only
Changes:
- Moved cryptogram, three_ds_action, cvc, external_three_ds from verification_options.card to payment_method.card
- Moved method from verification_options.*_direct_debit to payment_method.*_direct_debit and renamed it to verification_method
- Moved os_type and flow from verification_options.* to payment_method.*. Affected payment methods: alipaycn, alipayhk, dana, tng, gcash, truemoney, rabbit_line_pay, kakaopay
- Moved ip_address, flow, open_id from verification_options.wechatpay to payment_method.wechatpay

2024-01-31

This version introduces Batch Transfers resource and major changes to the Payments resource, notably relating to the payment status lifecycle, corresponding API endpoints and webhook events.
Updated payout statuses for better visibility on the state of the payment for the following endpoints (refer to payout statuses for further details):
- GET /api/v1/payments, response only
- GET /api/v1/payments/{payment_id}, response only
- POST /api/v1/payments/create, response only
Introduced the following endpoint to confirm funding for payments under the post-funding settlement model (refer to fund deduction for further details):
- POST /api/v1/payments/confirm_funding/{payment_id} * Deprecated the following endpoint:
- POST /api/v1/payments/retry/{payment_id} * Added funding object with additional funding information to the following endpoints:
- GET /api/v1/payments
- GET /api/v1/payments/{payment_id}
- POST /api/v1/payments/create
Changes:
- The funding object contains parsable information about funding of the payment:
  - deposit_type: Type of direct debit deposit created to fund the payment (with standard or accelerated settlement time)
  - failure_reason: Error code in the event of a rejected direct debit deposit
  - funding_source_id: The unique ID of the Linked Account used to fund the payment
  - status: Funding status of this payment (refer to funding statuses for further details)
Added batch_transfer_id for payments created via batch transfer to the following endpoints:
- GET /api/v1/payments, response only
- GET /api/v1/payments/{payment_id}, response only
Added remarks for including additional payment information (not passed to the beneficiary) to the following endpoints:
- GET /api/v1/payments, response only
- GET /api/v1/payments/{payment_id}, response only
- POST /api/v1/payments/create, request and response
- POST /api/v1/payments/validate, request only
Updated payment error codes (refer to payout error codes for details)
Updated payment failure reasons (refer to failure reasons for details):
Add a new failure reason 90502: TM suspended
Under post-funding workflow, payment_date will remain unchanged to reflect the original specified date for overdue payments. The date when the payment is sent will be returned in dispatch_date. This change is applicable to the following endpoints:
- GET /api/v1/payments, response only
- GET /api/v1/payments/{payment_id}, response only
Updated payment webhooks (refer to payout webhook for details):
- Add payment.scheduled
- Add payment.funding.requires_funding_confirmation
- Add payment.funding.scheduled
- Add payment.funding.processing
- Add payment.funding.funded
- Add payment.funding.reversed
- Add payment.funding.failed
- Add payment.overdue
- Add payment.processing
- Remove payment.new
- Remove payment.pending_funds
- Remove payment.in_review
- Remove payment.ready_for_dispatch
- Remove payment.suspended
- Remove payment.retried
- Update payment.rejected to payment.approval_rejected
- Update payment.recalled to payment.approval_recalled
- Update payment.blocked to payment.approval_blocked
- Update payment.dispatched to payment.sent

2023-10-01

Payment Acceptance notification webhook changes. The payload of new webhooks are aligned with PaymentDispute and different from the removed Dispute webhooks.
- Add payment_dispute.requires_response
- Add payment_dispute.expired
- Add payment_dispute.accepted
- Add payment_dispute.challenged
- Add payment_dispute.reversed
- Add payment_dispute.pending_decision
- Add payment_dispute.pending_closure
- Add payment_dispute.won
- Add payment_dispute.lost
- Remove dispute.rfi_received_by_merchant
- Remove dispute.rfi_responded_by_merchant
- Remove dispute.pre_chargeback_received_by_merchant
- Remove dispute.pre_chargeback_accepted
- Remove dispute.dispute_received_by_merchant
- Remove dispute.dispute_responded_by_merchant
- Remove dispute.pre_arbitration_received_by_merchant
- Remove dispute.arbitration_escalate_received_by_merchant
- Remove dispute.accepted
- Remove dispute.lost
- Remove dispute.won
- Remove dispute.dispute_reversed
Added an optional field store_details to account_details in the requests and responses of the following endpoints:
- GET /api/v1/accounts/{id}, response only
- GET /api/v1/accounts, response only
- GET /api/v1/account, response only
- POST /api/v1/accounts/create, request and response
- POST /api/v1/accounts/{id}/update, request and response
- POST /api/v1/accounts/{id}/submit, response only
- POST /api/v1/account/amendments/create, request and response
- GET /api/v1/account/amendments/{amendment_id}, response only

2023-08-31

Added country_code and language fields to create a Linked Account authentication.

Affected endpoints:
- POST /api/v1/linked_accounts/auth, request only
- POST /api/v1/linked_accounts/{id}/auth, request only
Added request_id to create a Linked Account for idempotency check. Calling Create a Linked Account via Open Banking verification with the same details as an existing Linked Account will create a new Linked Account, rather than deleting the existing one.

Affected endpoints:
- POST /api/v1/linked_accounts/create, request only
Replaced Delete a Linked Account with Suspend a Linked Account. After a Linked Account has been suspended, it can still be queried by calling Get a Linked Account by ID. Calling Create a Linked Account via micro-deposit verification with the same details as a suspended Linked Account will replace said suspended Linked Account, rather than generating a new one.

Affected endpoints:
- POST /api/v1/linked_accounts/{id}/delete New endpoints:
- POST /api/v1/linked_accounts/{id}/suspend

2023-06-30

This version introduces major changes to the request and response for creating, updating, submitting, retrieving Accounts of legal_entity_type = INDIVIDUAL.

Accounts of legal_entity_type = INDIVIDUAL in the UK and EU region are now supported with several new backing fields. For better consistency, the validation rules and data structures of individual_details have been aligned with business_person_details. account_usage for accounts of legal_entity_type = INDIVIDUAL is renewed for better risk rating. Also, a new identification type - TAX_ID is added to support US citizens and residents.

Impacted endpoints:
- GET /api/v1/account, response only
- GET /api/v1/accounts, response only
- GET /api/v1/accounts/{id}, response only
- POST /api/v1/accounts/create, request and response
- POST /api/v1/accounts/{id}/update, request and response
- POST /api/v1/accounts/{id}/submit, request and response
Changes:
- Added new fields to support individual onboarding in the UK region:
  - account_details.individual_details.occupation
  - account_details.individual_details.other_names
  - account_details.individual_details.employer
  - account_details.individual_details.estimated_monthly_income
- Added new field account_details.individual_details.account_usage, root level account_usage is removed.
- Renewed allowed values of some fields in the account_usage for better risk rating:
  - account_details.individual_details.account_usage.card_usage
  - account_details.individual_details.account_usage.collection_from
  - account_details.individual_details.account_usage.payout_to
- Added new fields in the account_usage:
  - account_details.individual_details.account_usage.product_reference
- Added new identification type TAX_ID with new fields of the Identification object:
  - tax_id.number
  - tax_id.type
- Renamed fields of the Identification object:
  - drivers_license.license_number to drivers_license.number
  - passport.passport_number to passport.number
  - personal_id.id_number to personal_id.number
- Simplified attachment tag options:
  - account_details.individual_details.attachments.individual_documents.tag
- Added new consent for collecting and processing the biometrics data:
  - customer_agreements.agreed_to_biometrics_consent
- Removed account_details.individual_details.user_id_on_platform, and the removed fields is replaced by identifier.
- Other renamed fields:
  - account_details.individual_details.address to account_details.individual_details.residential_address
  - account_details.individual_details.address_english to account_details.individual_details.residential_address_english
  - account_details.individual_details.photo_file_id to account_details.individual_details.live_selfie_file_id
  - account_details.individual_details.primary_identification to account_details.individual_details.identifications.primary
  - account_details.individual_details.secondary_identification to account_details.individual_details.identifications.secondary
- Other new fields:
  - account_details.individual_details.middle_name_english
  - account_details.individual_details.other_names
  - account_details.individual_details.account_usage.expected_monthly_transaction_volume.currency
- Other removed fields:
  - account_details.individual_details.reason_for_duplicate_account
Updated the success response from OK to "OK" for the following endpoints:
- POST /api/v1/beneficiaries/validate, response only
- POST /api/v1/payers/validate, response only
- POST /api/v1/payments/validate, response only
- POST /api/v1/payments/cancel, response only

2023-06-15

This version introduces major changes to the request and response for creating, updating, submitting, retrieving Accounts.

Notable change relates to removal of field-level validations linked to business_address, business_structure, and nationality of business_person_details. Removal of validations provides greater flexibility in meeting dynamic regulatory needs of each jurisdiction.

Impacted endpoints:
- GET /api/v1/account, response only
- GET /api/v1/accounts, response only
- GET /api/v1/accounts/{id}, response only
- POST /api/v1/accounts/create, request and response
- POST /api/v1/accounts/{id}/update, request and response
- POST /api/v1/accounts/{id}/submit, request and response
Changes:
- Removed field-level validations linked to business_address, business_structure, and nationality of business_person_details. Submitted accounts now use unified validation rules for all accounts of legal_entity_type = BUSINESS
- Consolidated business persons information
- account_details.authorised_person_details, account_details.beneficial_owners, account_details.controlling_person_details, account_details.director_details, account_details.legal_rep_details should be passed in new field account_details.business_person_details with account_details.business_person_details.roles specified
- Primary and secondary identification of business person now supported, old fields supplementary_identification_number and supplementary_identification_type should be passed in account_details.business_person_details.identifications.secondary
- Consolidated business identifiers
- Added new fields account_details.business_details.business_identifiers, which support most of identification for the business
- account_details.business_details.business_registration_number, account_details.business_details.tax_id and account_details.business_details.vat_numbers all move to account_details.business_details.business_identifiers
- Update industry category API, new field account_details.business_details.industry_category_code uses new industry category codes. See in Reference Data
- Added new field account_details.business_details.account_usage, root level account_usage is not used by business account
- Add new fields:
  - account_details.business_person_details
  - account_details.business_details.account_usage
  - account_details.business_details.business_identifiers
  - account_details.business_details.industry_category_code
  - account_details.trustee_details.business_details.business_person_details
  - account_details.trustee_details.business_details.business_name_trading
  - account_details.trustee_details.business_details.business_identifiers
  - account_details.trustee_details.business_details.industry_category_code
- Remove fields:
  - account_details.authorised_person_details
  - account_details.beneficial_owners
  - account_details.controlling_person_details
  - account_details.director_details
  - account_details.legal_rep_details
  - account_details.business_details.business_registration_number
  - account_details.business_details.industry_category
  - account_details.business_details.industry_category_level3
  - account_details.business_details.industry_sub_category
  - account_details.business_details.tax_id
  - account_details.business_details.vat_numbers
  - account_details.business_details.trust_name
  - account_details.trustee_details.business_details.beneficial_owners
  - account_details.trustee_details.business_details.director_details
  - account_details.trustee_details.business_details.business_registration_number
  - account_details.trustee_details.business_details.industry_category
  - account_details.trustee_details.business_details.industry_category_level3
  - account_details.trustee_details.business_details.industry_sub_category
- Rename fields:
  - account_details.business_details.address to account_details.business_details.registration_address
  - account_details.business_details.address_english to account_details.business_details.registration_address_english
  - account_details.trustee_details.business_details.address to account_details.trustee_details.business_details.registration_address
  - account_details.trustee_details.business_details.address_english to account_details.trustee_details.business_details.registration_address_english

2023-04-15

Updated request and response for creating, updating and validating a beneficiary:
- POST /api/v1/beneficiaries/create
- POST /api/v1/beneficiaries/update/{beneficiary_id}
- POST /api/v1/beneficiaries/validate
Updated request, response, and error codes for creating, validating and retrying a payment:
- POST /api/v1/payments/create
- POST /api/v1/payments/validate
- POST /api/v1/payments/retry/{payment_id}
Updated response and error codes when requesting an existing beneficiary or payment:
- GET /api/v1/beneficiaries
- GET /api/v1/beneficiaries/{beneficiary_id}
- GET /api/v1/payments
- GET /api/v1/payments/{payment_id}
Updated form schemas for CA, HK, IN, JP, MA, MX, NZ, AR, PE and all countries which require the iban field:
- POST /api/v1/beneficiary_api_schemas/generate
- POST /api/v1/beneficiary_form_schemas/generate
Removed update a payment:
- POST /api/v1/payments/update/{payment_id}

Changes:

bank_name is no longer required unless payment_methods is LOCAL and bank_country_code is CN.
bank_name will still be returned in the response, based on a mapping of your submitted bank details.
swift_code is no longer required when creating a beneficiary or a new payment, in all scenarios where iban is required. This includes if bank_country_code is one of AD, AE, AL, AT, AZ, BA, BE, BG, BH, BL, BY, CH, CY, CZ, DE, DK, DO, EE, ES, FI, FR, FO, GB, GE, GF, GG, GI, GL, GR, GT, HR, HU, IC, IE, IL, IM, IN, IS, IT, JE, JO, KW, KZ, LB, LC, LI, LT, LU, LV, MC, MD, MF, MK, MQ, MR, MT, MU, NC, NL, NO, PK, PL, PM, PS, PT, QA, RE, RO, RS, SA, SC, SE, SI, SK, SM, TL, TN, TR, VG, XK, TF, WF, YT; and when payment_methods is LOCAL, and account_currency is EGP.
account_routing_type1 and account_routing_value1 are no longer required when creating a beneficiary or a new payment where payment_methods is LOCAL, and account_currency is MAD, MXN, ARS, or PEN.
Where payment_methods is LOCAL and account_currency is JPY:
- account_routing_type1 is now defined as bank_code
- account_routing_type2 is now defined as branch_code
- account_routing_value2 is now required
- bank_account_category is now required
Where payment_methods is LOCAL and account_currency is CAD:
- account_routing_type1 is now defined as institution_number
- account_routing_type2 is now defined as transit_number
- account_routing_value2 is now required
Added error codes 082-089. Refer to the Payouts Product Docs for all potential error codes and descriptions

Beneficiaries created using POST /api/v1/beneficiaries/create on a previous API version will be compatible with this version without updating to the new schema. However, to update an existing beneficiary by calling POST /api/v1/beneficiaries/update/{beneficiary_id}, you will need to follow the new schema.

A new object failure_details has been added to the Deposit resource. Affected endpoints:
- GET /api/v1/deposits, response only
- GET /api/v1/deposits/{id}, response only
Changes:
- Refer to the Product Docs for all potential error codes and descriptions.

2022-12-13

Updated success response from an empty body to OK for the following endpoints:
- POST /api/v1/beneficiaries/validate, response only
- POST /api/v1/payers/validate, response only
- POST /api/v1/payments/validate, response only
- POST /api/v1/payments/cancel, response only
Updated the error response structure to be parsable for the following endpoints:
- POST /api/v1/beneficiaries/validate, response only
- POST /api/v1/beneficiaries/create, response only
- POST /api/v1/beneficiaries/update/{beneficiary_id}, response only
- POST /api/v1/payers/validate, response only
- POST /api/v1/payers/create, response only
- POST /api/v1/payers/update/{payer_id}, response only
- POST /api/v1/payments/validate, response only
- POST /api/v1/payments/create, response only
- POST /api/v1/payments/update/{payment_id}, response only
- POST /api/v1/payments/cancel, response only
- POST /api/v1/payments/retry, response only
Changes:
- Refreshed the error codes, which includes renaming, splitting, merging and retiring previous error codes
- Removed message and description from the response. Refer to the Payouts Product Docs for all potential error codes and descriptions
- Added params object with parsable information where applicable, e.g. payment amount limit, amount limit currency
- Replaced source in the error response of previous API version with errors in this version. The errors object contains source and code fields, as well as the params object (if applicable) that returns parsable details based on the specific error
- For a field validation error where code is validation_failed, the response contains an errors object that can return a list of source, code and params fields/objects corresponding to all the schema validation errors identified in the request:
- source: Specific field within the request that has failed schema validation
- code: Unique numeric identifier of the specific validation error encountered
- params: Additional parsable information related to the specific validation error where applicable, e.g. minimum and maximum character length
For a general error where code is not validation_failed, the errors object will be empty
A new endpoint can be used to close a Global Account:
- POST /api/v1/global_accounts/{id}/close
A new field close_reason has been added to the Global Account resource. Affected endpoints:
- GET /api/v1/global_accounts, response only
- POST /api/v1/global_accounts/update/{id}, response only
- GET /api/v1/global_accounts/{id}, response only
A new endpoint can be used to cancel a direct debit payout under the Direct Debit resource:
- POST /api/v1/direct_debits/{transaction_id}/cancel
A new field mandate_id has been added to the Direct Debit resource. Affected endpoints:
- GET /api/v1/direct_debits, response only
- GET /api/v1/direct_debits/{transaction_id}, response only
New endpoints that can be used to manage direct debit payout mandates under the Global Account resource:
- GET /api/v1/global_accounts/{global_account_id}/mandates/{id}
- GET /api/v1/global_accounts/{global_account_id}/mandates
- POST /api/v1/global_accounts/{global_account_id}/mandates/{id}/cancel
A new field mandate.direct_debit_deposit has been added to the Linked Account resource. Affected endpoints:
- GET /api/v1/linked_accounts, response only
- GET /api/v1/linked_accounts/{id}, response only
- POST /api/v1/linked_accounts/create, response only
- POST /api/v1/linked_accounts/{id}/verify_microdeposits, response only
A new field preferred_reference has been added to the request parameter mandate under the Linked Account resource. Affected endpoints:
- POST /api/v1/linked_accounts/create, request only
- POST /api/v1/linked_accounts/{id}/mandate, request only
Fields of Direct Debit mandate resource have been updated, under the Linked Account resource. Affected endpoints:
- GET /api/v1/linked_accounts/{id}/mandate, response only
- POST /api/v1/linked_accounts/{id}/mandate, response only
Changes:
- The values of field status should be: ACTIVE, INACTIVE, PROCESSING
- A new field reference has been added
- A new object field address has been added, including address.country_code, address.state, address.suburb, address.postcode, address.address_line1, address.address_line2
A new optional field deposit_conversion_currency has been added to the Global Account resource. Affected endpoints:
- POST /api/v1/global_accounts/update/{id}
- POST /api/v1/global_accounts/create
- GET /api/v1/global_accounts, response only
- GET /api/v1/global_accounts/{id}, response only
- POST /api/v1/global_accounts/{id}/close , response only

2022-11-14

Added transaction type to balance history endpoint Changed PAYMENT source transaction type to PAYOUT for balance history endpoint Changed description for Transfer Debit DEPOSIT_SPLIT subtype for balance history endpoint
GET /api/v1/balance/history

2022-11-11

PaymentConsent create/update requests will no longer take the payment_method payload. Impacted endpoints:
- POST /api/v1/pa/payment_consents/create, request only
- POST /api/v1/pa/payment_consents/{id}/update, request only

Instead, the user should provide the payment_method payload directly in the PaymentConsent verify request or the PaymentIntent confirm request (with a PENDING_VERIFICATION PaymentConsent):

POST /api/v1/pa/payment_consents/{id}/verify
POST /api/v1/pa/payment_intents/{id}/confirm * When verifying a PaymentConsent initiated by customer, if an existing VERIFIED PaymentConsent already references the provided card or bank account number, the request will be declined with resource_already_exists to avoid generating multiple identical PaymentConsents, which might confuse the shopper during return payment. Impacted endpoints:
- POST /api/v1/pa/payment_consents/{id}/verify * The id, status, created_at, and updated_at of the payment_method payload will only be available if the corresponding PaymentMethod resource exists. Therefore, for a one-off payment, these fields will be null in the API response. Impacted endpoints:
- POST /api/v1/pa/payment_intents/{id}/confirm, response only
- POST /api/v1/pa/payment_intents/{id}/confirm_continue, response only
- GET /api/v1/pa/payment_intents/{id}, response only
- GET /api/v1/pa/payment_attempts/{id}, response only
- GET /api/v1/pa/payment_attempts, response only
Next action type in a response from PaymentIntent and PaymentConsent related APIs will be redirect_iframe with GET next action method, when 3DS authentication is required. Also there will be no need to pass acs_response in confirm_continue request when redirect_iframe action is completed. Impacted endpoints:
- GET /api/v1/pa/payment_intents/{id}, response only
- POST /api/v1/pa/payment_intents/{id}/confirm, response only
- POST /api/v1/pa/payment_intents/{id}/confirm_continue, response only
- GET /api/v1/pa/payment_consents/{id}, response only
- POST /api/v1/pa/payment_consents/{id}/verify, response only
The error codes returned from the PaymentLink APIs are changed to standard text codes (previously digits). In addition, the timestamp format of PaymentLinks API responses is now standardized to 2022-11-11T12:12:12+0000. Impacted endpoints:
POST /api/v1/pa/payment_links/create, response only
POST /api/v1/pa/payment_links/{id}/update, response only
GET /api/v1/pa/payment_links/{id}, response only
POST /api/v1/pa/payment_links/{id}/notify_shopper, response only
POST /api/v1/pa/payment_links/{id}/activate, response only
POST /api/v1/pa/payment_links/{id}/delete, response only
GET /api/v1/pa/payment_links, response only

2022-10-14

New possible value FAILED added for the status of a Scale charge. Affected endpoints:
GET /api/v1/charges, response only
GET /api/v1/charges/{id}, response only
New possible values added for the status of a Scale transfer. Previously existing statuses: NEW and SETTLED. Newly added statuses: PENDING, FAILED, and SUSPENDED. Affected endpoints:
GET /api/v1/transfers, response only
GET /api/v1/transfers/{id}, response only

2022-10-10

When calling the following endpoint for an account for a business located in the United States:
POST /api/v1/accounts/{id}/submit * The following previously optional fields are now required:
- account_details.business_details.business_address.address_line1
- account_details.business_details.business_address.country_code
- account_details.business_details.business_address.postcode
- account_details.business_details.business_address.state
- account_details.business_details.business_address.suburb
- account_details.business_details.business_registration_number
- account_details.business_details.business_structure
- account_details.business_details.description_of_goods_or_services
- account_details.business_details.tax_id.number
- account_details.business_details.tax_id.type
- account_details.beneficial_owners.address.address_line1
- account_details.beneficial_owners.address.country_code
- account_details.beneficial_owners.address.postcode
- account_details.beneficial_owners.address.state
- account_details.beneficial_owners.address.suburb
- account_details.beneficial_owners.attachments must include one of PASSPORT or DRIVERS_LICENSE_FRONT and DRIVERS_LICENSE_BACK
- account_details.beneficial_owners.date_of_birth
- account_details.beneficial_owners.first_name
- account_details.beneficial_owners.last_name
- account_details.beneficial_owners.identification_number
- account_details.beneficial_owners.identification_type
At least one director or controlling person (a new field) is required, and if included the following previously optional fields are required:
- account_details.director_details.address.address_line1
- account_details.director_details.address.country_code
- account_details.director_details.address.postcode
- account_details.director_details.address.state
- account_details.director_details.address.suburb
- account_details.director_details.attachments must include one of PASSPORT or DRIVERS_LICENSE_FRONT and DRIVERS_LICENSE_BACK
- account_details.director_details.date_of_birth
- account_details.director_details.first_name
- account_details.director_details.last_name
- account_details.director_details.identification_number
- account_details.director_details.identification_type
- account_details.controlling_person_details.address.address_line1 (new field)
- account_details.controlling_person_details.address.country_code (new field)
- account_details.controlling_person_details.address.postcode (new field)
- account_details.controlling_person_details.address.state (new field)
- account_details.controlling_person_details.address.suburb (new field)
- account_details.controlling_person_details.attachments must include one of PASSPORT or DRIVERS_LICENSE_FRONT and DRIVERS_LICENSE_BACK
- account_details.controlling_person_details.date_of_birth (new field)
- account_details.controlling_person_details.first_name (new field)
- account_details.controlling_person_details.last_name (new field)
- account_details.controlling_person_details.identification_number (new field)
- account_details.controlling_person_details.identification_type (new field)
- account_details.controlling_person_details.job_title (new field)
- account_details.controlling_person_details.nationality (new field)
The following previously required fields are now optional:
- account_usage.card_usage
- account_usage.collection_country_codes
- account_usage.collection_from
- account_usage.expected_monthly_transaction_volume.amount
- account_usage.payout_country_codes
- account_usage.payout_to
The following new fields are required for those with US nationality:
- account_details.beneficial_owners.supplementary_identification_type must be one of SSN or ITIN
- account_details.beneficial_owners.supplementary_identification_number must be 9 digits
- account_details.director_details.supplementary_identification_type must be one of SSN or ITIN
- account_details.director_details.supplementary_identification_number must be 9 digits
The following new fields are optional:
- account_details.authorised_person_details.supplementary_identification_type
- account_details.authorised_person_details.supplementary_identification_number
- account_details.legal_rep_details.supplementary_identification_type
- account_details.legal_rep_details.supplementary_identification_number
All addresses with a US country code require a two-letter abbreviation for state. Impacted fields:
- account_details.business_details.business_address.state
- account_details.beneficial_owners.address.state
- account_details.controlling_person_details.address.state
- account_details.director_details.address.state
- account_details.legal_rep_details.address.state
- account_details.trustee_details.business_details.address.state
- account_details.trustee_details.individual_details.address.state
Add supplementary_identification_type and supplementary_identification_number to authorised_person_details, beneficial_owners, director_details, and legal_rep_details. Impacted endpoints:
- GET /api/v1/account
- GET /api/v1/accounts
- POST /api/v1/accounts/create
- GET /api/v1/accounts/{id}
- POST /api/v1/accounts/{id}/submit
- POST /api/v1/accounts/{id}/update

2022-10-04

Changed Financial Transaction responses from camelCase to snake_case. Affected endpoints:
- GET /api/v1/financial_transactions
- GET /api/v1/financial_transactions/{id}

2022-09-09

Enhanced the beneficiary schema definitions for supported payout capabilities to be available based on the account attributes, such as business registration region, industry category.
Added example fields that can be used to help end users understand what to enter for each field.
Updated flight time and transfer limit to be parsable fields:
Replaced the sub field processing_time with flight_time under field payment_method options with min and max json nodes
Replaced the sub field payment_limit to transfer_limit under field payment_method options with min and max json nodes (Note that max node will be hidden if there is no transfer limit)

Affected endpoints:
- POST /api/v1/beneficiary_form_schemas/generate, response only

2022-02-16

Enrich and re-construct the schema of Global Account detail to return the necessary information. Affected endpoints:
- GET /api/v1/global_accounts, response only
- GET /api/v1/global_accounts/{id}, response only
- POST /api/v1/global_accounts/create, response only
- POST /api/v1/global_accounts/update/{id}, response only
Extend the Global Account transaction status, the possible values can be one of 'PENDING', 'SETTLED', 'REJECTED', 'CANCELLED' Affected endpoints:
- GET /api/v1/global_accounts/{id}/transactions, response only
Lastly, this endpoint is deprecated:
- GET /api/v1/reference/settlement_accounts

2021-11-25

Use new redirect_form next_action type for 3DS flow.

2021-10-11

Scale accounts now onboarded to respective local Airwallex entity based on the created account's business address country code. Validation rules for account submission no longer driven by the Owning entity of the account creator. Affected endpoint:
POST /api/v1/accounts/{id}/submit

2021-08-06

Remove pci- subdomain prefix - the standard subdomain is now pci-compliant. Affected endpoints:
- /api/v1/pa
- /api/v1/issuing
- /api/v1/financial_transactions
Rename Financial Transactions endpoints and add support for on-behalf-of header
- **GET /api/v1/pa/financial/transactions** -> GET /api/v1/financial_transactions
- GET /api/v1/pa/financial/transactions/{id} -> GET /api/v1/financial_transactions/{id}
Rename Refund status PROCESSING to ACCEPTED. Impacted endpoints are:
- GET /api/v1/pa/refunds*
- POST /api/v1/pa/refunds/create
Move billing inside card (previously both at the same level under payment_method). Impacted endpoints are:
- GET /api/v1/pa/payment_intents/{id}
- POST /api/v1/pa/payment_intents/confirm
- GET /api/v1/pa/payment_attempts*
- GET /api/v1/pa/customers/{id}
- POST /api/v1/pa/customers/{id}/add_payment_method
- POST /api/v1/pa/customers/{id}/remove_payment_method
- GET /api/v1/pa/payment_methods*
- POST /api/v1/pa/payment_methods*
Remove supplementary_amount from PaymentIntent. Also deprecate customer_payment_methods and customer_payment_consents from PaymentIntent create response. Impacted endpoints are:
- GET /api/v1/pa/payment_intents*
- POST /api/v1/pa/payment_intents/create
Payment Acceptance notification webhook changes
- Rename payment_intent.payment_method_required to payment_intent.requires_payment_method
- Rename payment_intent.capture_required to payment_intent.requires_capture
- Rename payment_intent.customer_action_required to payment_intent.requires_customer_action
- Rename refund.processing to refund.accepted
- Deprecate payment_method.creation_failed
- Deprecate payment_method.update_failed
- Deprecate payment_method.attachment_failed
- Deprecate payment_method.detachment_failed
- Deprecate payment_method.disable_failed
- Deprecate customer.creation_failed
- Deprecate customer.update_failed
Payment Acceptance error code changes
- Rename service_unavailable to internal_error
- Rename state_invalid_for_operation to invalid_status_for_operation
- Rename processor_declined to provider_declined
- Rename processor_unavailable to provider_unavailable

2021-07-01

Business structure SELF_MANAGED_SUPER_FUND is now supported for Australian businesses, and the following new fields have been added to the account resource:
- account_details.trustee_details
  
  Affected endpoints:
  - GET /api/v1/account, response only
  - GET /api/v1/accounts, response only
  - GET /api/v1/accounts/{id}, response only
  - POST /api/v1/accounts/create, request and response
  - POST /api/v1/accounts/{id}/update, request and response
  - POST /api/v1/accounts/{id}/submit, response only
  - POST /api/v1/accounts/{id}/terms_and_conditions/agree, response only
For Australian business accounts, the following fields are now required:
- account_details.authorised_person_details.first_name
- account_details.authorised_person_details.last_name
- account_usage
And for Australian business accounts, the following fields are no longer required:
- account_details.beneficial_owners.identification_number
- account_details.beneficial_owners.identification_type
- account_details.beneficial_owners.attachments.identity_files
Affected endpoints:
- POST /api/v1/accounts/{id}/submit
New endpoints for platform manage Scale Connect invitation links:
- POST /api/v1/accounts/invitation_links/create: Creates an Account Link object that includes an Airwallex hosted url for the end user to accept a scale connect invitation sent by the platform account.
- GET /api/v1/accounts/invitation_links/{id}: Get an Account Link by link Id.

Affected versions: all

Added the following endpoint to retrieve a tree of options for industry_category, industry_sub_category, and industry_category_level3:
- GET /api/v1/reference/industry_categories
Added the following fields:
- account_details.business_details.description_of_goods_and_services
- account_details.business_details.description_of_industry
- account_details.business_details.industry_category_level3
Affected endpoints:
- GET /api/v1/account, response only
- GET /api/v1/accounts, response only
- GET /api/v1/accounts/{id}, response only
- POST /api/v1/accounts/create, request and response
- POST /api/v1/accounts/{id}/update, request and response
- POST /api/v1/accounts/{id}/submit, response only
- POST /api/v1/accounts/{id}/terms_and_conditions/agree, response only

Affected versions: all

2021-02-28

For HK business accounts, the following fields are no longer required:
- account_details.business_details.business_name
- account_details.business_details.business_registration_number
- account_details.business_details.address.state
- account_details.business_details.address.suburb
- account_details.business_details.address.address_line1
- date_of_birth, first_name, first_name_english, last_name, last_name_english, identification_number under account_details.director_details and account_details.beneficial_owners if the individual's identity documents have HK nationality.
For CN business accounts, the following fields are no longer required:
- account_details.business_details.business_structure
Impacted urls are：
- POST /api/v1/accounts/{id}/submit
Added new optional field for business accounts: account_usage. Impacted urls are：
- GET /api/v1/account
- GET /api/v1/accounts
- GET /api/v1/accounts/{id}
- POST /api/v1/accounts/create
- POST /api/v1/accounts/{id}/update
- POST /api/v1/accounts/{id}/submit
Added new option to status field: ACTION_REQUIRED, and created a new web hook for when an account goes into this status.

When the account is in this status, check the requirements field for further details on the actions required.

The new status can appear in responses to the following endpoints:
- GET /api/v1/account, response only
- GET /api/v1/accounts, response only
- GET /api/v1/accounts/{id}, response only
- POST /api/v1/accounts/create, response only
- POST /api/v1/accounts/{id}/update, response only
- POST /api/v1/accounts/{id}/submit, response only
Agreement to terms and conditions is not required for account submission, only for account activation. An account which passes review without customer_agreements.agreed_to_terms_and_conditions = true will have a status of ACTION_REQUIRED. It will also have the following new fields:
- next_action.type = "agreement_to_terms_and_conditions_required"
- requirements.agreement_to_terms_and_conditions_required.endpoint = "/api/v1/accounts/{id}/terms_and_conditions/agree"
- requirements.agreement_to_terms_and_conditions_required.method = "POST"
- requirements.agreement_to_terms_and_conditions_required.message = "Account has passed review. To activate the account, please agree to the terms and conditions by calling the endpoint."
A new endpoint can be used to agree to terms and conditions:
- POST /api/v1/accounts/{id}/terms_and_conditions/agree

2020-12-06

Improved the error responses for payment validation and creation, so that validation errors are easier to parse. This field has also been added to the response:
- POST /api/v1/payments/create: response only
- POST /api/v1/payments/validate: response only
- POST /api/v1/payments/update/{payment_id}: response only
Added POST /api/v1/beneficiary_api_schemas/generate, a new endpoint that enables users to obtain required fields and associated validation rules.
Added POST /api/v1/beneficiary_form_schemas/generate, a new endpoint that provides UI definitions for users to create a beneficiary form that can change dynamically with the payment field requirement change made by Airwallex.

2020-11-08

Individual accounts are now supported, and the following new fields have been added to the account resource:
- account_details.individual_details, only used for individual accounts
- account_details.legal_entity_type, can be set to BUSINESS or INDIVIDUAL, defaults to BUSINESS
- account_usage
- customer_agreements
- primary_contact.mobile
This field has also been added to the response:
- requirements, currently only used for individual accounts
In addition, these fields have been eliminated for business accounts, replaced by similar fields in the new customer_agreements field:
- Removed: account_details.business_details.agreed_to_terms
- Added: customer_agreements.agreed_to_terms_and_conditions
- Removed: account_details.business_details.opt_in_for_marketing
- Added: customer_agreements.opt_in_for_marketing
These changes apply to the following endpoints:
- GET /api/v1/account, response only
- GET /api/v1/accounts, response only
- GET /api/v1/accounts/{id}, response only
- POST /api/v1/accounts/create, request and response
- POST /api/v1/accounts/{id}/update, request and response
- POST /api/v1/accounts/{id}/submit, response only
Lastly, this endpoint is deprecated:
- POST /api/v1/accounts/{id}/clone

2020-09-28

Enhanced card creation and updating to take into account cardholder details and verification requirements.
- POST /api/v1/cards/create:
  - The name_on_card field has been deprecated.
  - When issue_to is set to ORGANISATION, the business's name will be used as the name on card.
  - When issue_to is set to INDIVIDUAL, the cardholder_id field is required and the cardholder's name will be used as the name on card.
  - The primary_contact_details field is no longer required. These details may be set only when issue_to is set to ORGANISATION.
  - Added primary_contact_details.email.
  - Removed primary_contact_details.date_of_birth.
  - Added validation for primary_contact_details.mobile_number
- POST /api/v1/cards/{id}/update:
  - Added the ability to update primary contact details for expense cards.

2020-04-30

Renamed Payment Attempt statuses
- PENDING to AUTHENTICATION_REDIRECTED
- SUCCEEDED to CAPTURE_REQUESTED
- VOIDED to CANCELLED
- PROCESSING to RECEIVED
- REDIRECT_AUTHENTICATION to AUTHENTICATION_REDIRECTED
- REQUESTED_CAPTURE to CAPTURE_REQUESTED
  
  Impacted urls are:
  - /api/v1/pa/payment_intents/
  - /api/v1/pa/payment_attempts/

2019-09-09

Updated validation failed error response of the following endpoints for greater integration contract clarity. Full validation error details will no longer be returned from create/update, and should instead be obtained by calling the relevant validate endpoint prior to submission. Specifically: for errors with code payment_schema_validation_failed, details field has been removed, and source and message will now reflect the first validation error.
POST /api/v1/beneficiaries/create POST /api/v1/beneficiaries/update/{beneficiary_id} POST /api/v1/payers/create POST /api/v1/payers/update/{payer_id} POST /api/v1/payments/create POST /api/v1/payments/update/{payment_id}

Removed details field from error responses of all other endpoints, for increased contract clarity. The contents of this field did not add any value beyond what's already in source and message, and was not documented accurately or usefully. A more useful details field will likely be introduced in the future.
/api/v1/ (all endpoints)
- Enhancement of validation rules and requirement of fields for Account create/update/submit endpoints for UK and AU entity
POST /api/v1/accounts/create and POST /api/v1/accounts/{id}/update have revised submission requirements:
- Added new fields: account_details.beneficial_owners.address for specifying beneficial owners address information.
- Added new fields: account_details.director_details.address for specifying director personal address information.
- Added new fields: account_details.legal_rep_details.address for specifying legal rep personal address information.
- Added new fields: account_details.business_details.as_trustee,account_details.business_details.trust_name for specifying acting in capacity as a trustee.
- Added new fields: account_details.business_details.vat_numbers for specifying Value Added Tax (VAT) in a particular state.
- Added new object: account_details.authorised_person_details for specifying person purporting to act information specific to AU entity.
- Updated fields account_details.business_details.industry_category, account_details.business_details.industry_sub_category, account_details.business_details.purpose.
POST /api/v1/accounts/{id}/submit
- Updated validation rules for fields for UK and AU entity, (some previously optional fields are now conditionally required for submission).
- Updated validation rules for the category of industry.
- Updated validation rules for sub industry category with enumeration.
- Updated validation rules for the purpose with enumeration.

2017-01-01

This is the initial version of Airwallex API.

Was this page helpful?