--- title: Changelog description: 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. --- 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-08-21 * **POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`**: added the optional `auto_close_date` request field. If provided, the card is automatically closed at the start of the specified day (00:00 GMT). The date must be in the format YYYY-MM-DD and must be at least 1 day and no more than 5 years after the request is made. If not provided on create, the card is not automatically closed and follows the standard expiry and reissue behavior. On update, set the field to `null` to clear the scheduled closure; if omitted, the current value is maintained. * **GET `/api/v1/issuing/cards/{id}`, POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`** responses: added `auto_close_date`. The date on which the card is automatically closed, at the start of that day (00:00 GMT), in the format YYYY-MM-DD. Returns `null` if no automatic closure is scheduled. * **POST `/api/v1/issuing/cards/create`**: added the `program.bin` request field. Optional 6- or 8-digit network BIN. If provided, the requested BIN is used only if it is active, mapped to your program, and compatible with the card; otherwise the request is rejected with `ineligible_bin`. If omitted, Airwallex selects an eligible BIN automatically. Values that are not 6 or 8 digits return `invalid_bin_format`. This field is available only to accounts enabled for BIN selection. * The account `status` field now exposes two additional values, `DORMANT` and `CLOSED`, providing a more granular view of inactive accounts. On earlier API versions, dormant accounts were returned as `ACTIVE`, and closed accounts were returned as `SUSPENDED`. Affected endpoints: * **GET `/api/v1/accounts`**, request and response * **GET `/api/v1/accounts/{id}`**, response only Changes: * `status`: added two new values to the account `status` field: * `DORMANT`: The account has been marked dormant due to prolonged inactivity and must initiate a transaction to trigger a reactivation review. * `CLOSED`: The account is permanently closed after the pending-closure grace period and cannot be reactivated. * `account_status`: the `GET /api/v1/accounts` query parameter now also accepts `DORMANT` and `CLOSED` as filter values. * After a completed offboarding, the account enters pending closure and the client API returns `SUSPENDED` on all API versions. After a 30-day grace period the account is permanently closed; on this version that surfaces as `CLOSED` (earlier versions continue to return `SUSPENDED`). * New account webhook events for the added statuses: * `account.dormant` * `account.closed` * Spend accounting field selections now use `source_id` as the internal accounting-value identifier. For Bills and Purchase Orders, create requests replace the legacy `identifier_type`, `field_id`, and `field_value_id` fields with required `type` and `source_id` fields. Responses now include `source_id` in embedded accounting field selections. Affected endpoints: * **GET `/api/v1/spend/bills`** * **GET `/api/v1/spend/bills/{id}`** * **POST `/api/v1/spend/bills/create`** * **POST `/api/v1/spend/bills/{id}/sync`** * **POST `/api/v1/spend/bills/{id}/mark_as_paid`** * **GET `/api/v1/spend/purchase_orders`** * **GET `/api/v1/spend/purchase_orders/{id}`** * **POST `/api/v1/spend/purchase_orders/create`** * **POST `/api/v1/spend/purchase_orders/{id}/sync`** * **GET `/api/v1/spend/expenses`** * **GET `/api/v1/spend/expenses/{id}`** * **POST `/api/v1/spend/expenses/{id}/sync`** * **GET `/api/v1/spend/reimbursement_reports`** * **GET `/api/v1/spend/reimbursement_reports/{id}`** * **POST `/api/v1/spend/reimbursement_reports/{id}/sync`** * **POST `/api/v1/spend/reimbursement_reports/{id}/mark_as_paid`** * **GET `/api/v1/spend/reimbursement_reports/{id}/reimbursements`** * **GET `/api/v1/spend/reimbursement_reports/{id}/reimbursements/{reimbursement_id}`** Changes: * Bill and Purchase Order create requests: replace `identifier_type`, `field_id`, and `field_value_id` with required `type` and `source_id` fields. * Accounting field selection responses: add `source_id`, the unique identifier of the selected accounting value. * Accounting field selection `type`: remove unsupported values `SUBSIDIARY`, `CLASS`, `DEPARTMENT`, `LOCATION`, and `PROJECT`. Bill, Purchase Order, Reimbursement, and Expense line-item selections support `GENERAL_LEDGER_ACCOUNT`, `TAX_CODE`, and `OTHER`; root Expense selections use `MERCHANT`. * Spend Bill and Expense webhook payloads now include `source_id` for populated accounting field selections. Affected webhook events: * `spend.bill.awaiting_approval` * `spend.bill.awaiting_payment` * `spend.bill.payment_in_progress` * `spend.bill.paid` * `spend.bill.rejected` * `spend.bill.scheduled` * `spend.bill.deleted` * `spend.bill.updated` * `spend.expense.draft` * `spend.expense.awaiting_approval` * `spend.expense.rejected` * `spend.expense.approved` * `spend.expense.archived` * `spend.expense.deleted` * `spend.expense.updated` Changes: * `data.line_items[].accounting_field_selections[].source_id`: added to Bill webhook payloads. * `data.accounting_field_selections[].source_id` and `data.line_items[].accounting_field_selections[].source_id`: added to Expense webhook payloads. * The Card Transaction Event response field `transaction_date_time` is renamed to `transacted_at`. Affected endpoints: * **GET `/api/v1/issuing/card_transaction_events`** (response only) * **GET `/api/v1/issuing/card_transaction_events/{id}`** (response only) Changes: * `transaction_date_time`: renamed to `transacted_at`. The field contains the ISO 8601 date and time reported by the card network. * Transaction Disputes now use Card Transaction Event identifiers. Affected endpoints: * **GET `/api/v1/issuing/transaction_disputes`** (query parameters and response) * **GET `/api/v1/issuing/transaction_disputes/{id}`** (response only) * **POST `/api/v1/issuing/transaction_disputes/create`** (request and response) * **POST `/api/v1/issuing/transaction_disputes/{id}/update`** (response only) * **POST `/api/v1/issuing/transaction_disputes/{id}/submit`** (response only) * **POST `/api/v1/issuing/transaction_disputes/{id}/cancel`** (response only) Changes: * Create Transaction Dispute: `card_transaction_event_id` is required; `transaction_id` is removed. * List Transaction Disputes: the `transaction_id` query parameter is removed. * Transaction Dispute responses: `transaction_id` is removed. Use `card_transaction_event_id` to identify the disputed event. * The sandbox-only Issuing Simulation API now uses Card Transaction Event fields and card transaction lifecycle identifiers. Affected endpoints: * **POST `/api/v1/simulation/issuing/create`** (request and response) * **POST `/api/v1/simulation/issuing/refund`** (request and response) * **POST `/api/v1/simulation/issuing/card_transaction_lifecycles/{card_transaction_lifecycle_id}/capture`** (path and response) * **POST `/api/v1/simulation/issuing/card_transaction_lifecycles/{card_transaction_lifecycle_id}/reverse`** (path and response) Changes: * Create and refund requests: replace `transaction_id` with `card_transaction_lifecycle_id`. * Capture and reverse: replace the `{transaction_id}` path with `{card_transaction_lifecycle_id}`. * Responses: replace `transaction_id` with `card_transaction_event_id`, `card_transaction_id`, and `card_transaction_lifecycle_id`; replace `posted_date` with `updated_at`, `status` with `process_result`, `transaction_date` with `transacted_at`, and `transaction_type` with `type` and `subtype`. ## 2026-07-17 * **POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`**: added the optional `auto_close_date` request field. If provided, the card is automatically closed at the start of the specified day (00:00 GMT). The date must be in the format YYYY-MM-DD and must be at least 1 day and no more than 5 years after the request is made. If not provided on create, the card is not automatically closed and follows the standard expiry and reissue behavior. On update, set the field to `null` to clear the scheduled closure; if omitted, the current value is maintained. * **GET `/api/v1/issuing/cards/{id}`, POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`** responses: added `auto_close_date`. The date on which the card is automatically closed, at the start of that day (00:00 GMT), in the format YYYY-MM-DD. Returns `null` if no automatic closure is scheduled. * `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 that have no associated card transaction lifecycle). 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 whose transaction has no associated card transaction lifecycle. 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](https://www.airwallex.com/docs/developer-tools/webhooks/listen-for-webhook-events.md) for more details) ## 2025-06-30 * This version includes major changes to the [Transfers](https://www.airwallex.com/docs/api/payouts/transfers.md) 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](https://www.airwallex.com/docs/developer-tools/webhooks/listen-for-webhook-events.md) 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](https://www.airwallex.com/docs/developer-tools/webhooks/listen-for-webhook-events.md) 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](https://www.airwallex.com/docs/api/payouts/transfers.md) 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](https://www.airwallex.com/docs/api/payouts/batch_transfers.md) 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](https://www.airwallex.com/docs/api/payouts/beneficiaries.md) 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](https://www.airwallex.com/docs/developer-tools/webhooks/listen-for-webhook-events.md) for more details) * Updated **Transfer**, **Batch Transfer**, **Beneficiary**, and **Payer** error code format (refer to [transfer error codes](https://www.airwallex.com/docs/payouts/errors/transfer-error-codes.md) and [batch transfer error codes](https://www.airwallex.com/docs/payouts/errors/batch-transfer-error-codes.md) 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](https://www.airwallex.com/docs/global-treasury/reporting/financial-reports/transaction-reconciliation-report.md) and [Balance Activity Report](https://www.airwallex.com/docs/global-treasury/reporting/financial-reports/balance-activity-report.md). 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](https://www.airwallex.com/docs/api/finance/financial_transactions.md) 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](https://www.airwallex.com/docs/api/2024-08-07/core_resources/global_accounts.md) 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](https://www.airwallex.com/docs/global-treasury/receive-funds/receive-bank-transfers-to-global-accounts/retrieve-your-deposits.md) 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](https://www.airwallex.com/docs/api/2024-08-07/core_resources/deposits/list.md) 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](https://www.airwallex.com/docs/developer-tools/webhooks/listen-for-webhook-events/deposits.md) 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](https://www.airwallex.com/docs/api/2024-04-30/payouts/payments.md) and [Beneficiaries](https://www.airwallex.com/docs/api/2024-04-30/payouts/beneficiaries.md) 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](https://www.airwallex.com/docs/payouts/transfers/create-a-transfer/transfer-statuses.md) 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](https://www.airwallex.com/docs/developer-tools/webhooks/listen-for-webhook-events/transfers.md) 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](https://www.airwallex.com/docs/payouts/payout-network/bank-accounts/united-states.md), 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 * **POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`**: added the optional `auto_close_date` request field. If provided, the card is automatically closed at the start of the specified day (00:00 GMT). The date must be in the format YYYY-MM-DD and must be at least 1 day and no more than 5 years after the request is made. If not provided on create, the card is not automatically closed and follows the standard expiry and reissue behavior. On update, set the field to `null` to clear the scheduled closure; if omitted, the current value is maintained. * **GET `/api/v1/issuing/cards/{id}`, POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`** responses: added `auto_close_date`. The date on which the card is automatically closed, at the start of that day (00:00 GMT), in the format YYYY-MM-DD. Returns `null` if no automatic closure is scheduled. * 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](https://www.airwallex.com/docs/issuing/transactions/transaction-failure-reasons.md) for details ## 2024-03-31 * **POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`**: added the optional `auto_close_date` request field. If provided, the card is automatically closed at the start of the specified day (00:00 GMT). The date must be in the format YYYY-MM-DD and must be at least 1 day and no more than 5 years after the request is made. If not provided on create, the card is not automatically closed and follows the standard expiry and reissue behavior. On update, set the field to `null` to clear the scheduled closure; if omitted, the current value is maintained. * **GET `/api/v1/issuing/cards/{id}`, POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`** responses: added `auto_close_date`. The date on which the card is automatically closed, at the start of that day (00:00 GMT), in the format YYYY-MM-DD. Returns `null` if no automatic closure is scheduled. * 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](https://www.airwallex.com/docs/api/2024-01-31/payouts/batch_transfers.md) resource and major changes to the [Payments](https://www.airwallex.com/docs/api/2024-01-31/payouts/payments.md) 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](https://www.airwallex.com/docs/payouts/transfers/create-a-transfer/transfer-statuses.md) 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](https://www.airwallex.com/docs/payouts/transfers/create-a-transfer.md) 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](https://www.airwallex.com/docs/payouts/transfers/create-a-transfer/transfer-statuses.md#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](https://www.airwallex.com/docs/payouts/errors/transfer-error-codes.md) for details) * Updated payment failure reasons (refer to [failure reasons](https://www.airwallex.com/docs/payouts/transfers/manage-transfers/failure-reasons.md) 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](https://www.airwallex.com/docs/developer-tools/webhooks/listen-for-webhook-events/transfers.md) 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](https://www.airwallex.com/docs/api/supporting_services/reference_data.md) * 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](https://www.airwallex.com/docs/payouts/older-api-versions/transfers/error-codes.md#field-validation-errors-with-example-response) 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](https://www.airwallex.com/docs/global-treasury/receive-funds/add-funds-via-direct-debits-from-linked-accounts/direct-debit-deposit-error-codes.md) 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](https://www.airwallex.com/docs/payouts/older-api-versions/transfers/error-codes.md#field-validation-errors-with-example-response) 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 * **POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`**: added the optional `auto_close_date` request field. If provided, the card is automatically closed at the start of the specified day (00:00 GMT). The date must be in the format YYYY-MM-DD and must be at least 1 day and no more than 5 years after the request is made. If not provided on create, the card is not automatically closed and follows the standard expiry and reissue behavior. On update, set the field to `null` to clear the scheduled closure; if omitted, the current value is maintained. * **GET `/api/v1/issuing/cards/{id}`, POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`** responses: added `auto_close_date`. The date on which the card is automatically closed, at the start of that day (00:00 GMT), in the format YYYY-MM-DD. Returns `null` if no automatic closure is scheduled. * 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 * **POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`**: added the optional `auto_close_date` request field. If provided, the card is automatically closed at the start of the specified day (00:00 GMT). The date must be in the format YYYY-MM-DD and must be at least 1 day and no more than 5 years after the request is made. If not provided on create, the card is not automatically closed and follows the standard expiry and reissue behavior. On update, set the field to `null` to clear the scheduled closure; if omitted, the current value is maintained. * **GET `/api/v1/issuing/cards/{id}`, POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`** responses: added `auto_close_date`. The date on which the card is automatically closed, at the start of that day (00:00 GMT), in the format YYYY-MM-DD. Returns `null` if no automatic closure is scheduled. * 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 * **POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`**: added the optional `auto_close_date` request field. If provided, the card is automatically closed at the start of the specified day (00:00 GMT). The date must be in the format YYYY-MM-DD and must be at least 1 day and no more than 5 years after the request is made. If not provided on create, the card is not automatically closed and follows the standard expiry and reissue behavior. On update, set the field to `null` to clear the scheduled closure; if omitted, the current value is maintained. * **GET `/api/v1/issuing/cards/{id}`, POST `/api/v1/issuing/cards/create`, POST `/api/v1/issuing/cards/update`** responses: added `auto_close_date`. The date on which the card is automatically closed, at the start of that day (00:00 GMT), in the format YYYY-MM-DD. Returns `null` if no automatic closure is scheduled. This is the initial version of Airwallex API.