Transfer statuses (older versions)

Handle failed transfers (older versions)

Transfer webhooks (older versions)

Error codes (older versions)

Transfers

A quick introduction to building with Airwallex APIs

Quickstart

Explore our comprehensive reference to integrate with Airwallex API endpoints

API Reference

Learn how to receive push notifications via webhooks

Webhooks

This page describes the status transitions for transfers on __API version 2023-10-01 or earlier__.

![transfer statuses 2023](//images.ctfassets.net/c3n7jozh84hr/35br1DGeHB4KsQlrwKN8NS/5e431b7d0520f97dd3fa17fa534c2ad6/payout_statuses_2023.png) 

Statuses for [transfer approvals](/payouts__manage-payouts__manage-approvals-for-payouts):

![transfer approval 2023 new style](//images.ctfassets.net/c3n7jozh84hr/6YmBHJ43XIdoxIJ4cCuYJ9/16e9d5413eeb456d589d678e7b984d7b/image.png)

| **Status** | **Description** | **Webhook Event Type**  |  **Next steps**|
| ---------- | --------- | --------- | --------- |
| NEW    | You have successfully created the transfer to be processed by Airwallex. If the transaction is scheduled for a future date, it will remain in this status until that date.| `payment.new` | No action needed.|
| IN_APPROVAL* | The transfer is submitted for approval. | `payment.in_approval` | Approvers can review the transfer in the web app. | 
| RECALLED* | The transfer is recalled by a user in the web app. | `payment.recalled` | Users can edit and resubmit the transfer in the web app.| 
| REJECTED* | The transfer is rejected by an approver in the web app. | `payment.rejected` | Users can edit and resubmit the transfer in the web app.| 
| BLOCKED* | Transfer is blocked as next approver cannot be found | `payment.blocked` | Account owner or Admin users can edit the Transfers approval workflow and resubmit the transfer in the web app. | 
| PENDING_FUNDS* | Transfer is waiting for funds to be available. | `payment.pending_funds` | No action needed. | 
| IN_REVIEW    | The transfer is on hold and being reviewed by Airwallex. We may request for additional information from you via email. Once the review is completed, the transfer will automatically transition to `READY_FOR_DISPATCH`. If the transfer cannot be processed after the review, its status will transition to `SUSPENDED`. | `payment.in_review` | No action needed unless Airwallex requests for additional information.|
| READY_FOR_DISPATCH   | The transfer is ready for dispatch and will typically remain in this status if it is past the cut-off time of our downstream partner.  | `payment.ready_for_dispatch` | No action needed.|
| DISPATCHED   | The transfer has been dispatched from Airwallex and will remain in this status if successful. Note that transfers may subsequently fail our banking partners’ processing or be rejected by the recipient bank, at which point its status will transition to `FAILED`. | `payment.dispatched`| No action needed. |
| FAILED   | The transfer has failed our banking partner's processing or was rejected by the recipient bank. Failed transfers will be automatically cancelled after a certain time depending on the region you are in. Please reach out to your Account Manager to find out more.| `payment.failed`| Before a failed transfer is automatically cancelled, you can either [Retry](/api#/Payouts/Payments/_api_v1_payments_retry__payment_id_/post)or [Cancel](/api#/Payouts/Payments/_api_v1_payments_cancel__payment_id_/post) it. See [Handle failed transfers](/payouts__manage-payouts__handle-failed-payouts) to determine the next step based on your failure reason.|
| RETRIED   | The failed transfer has been retried with updated details. The `RETRIED` status is the end state for the original transfer, and a new transfer is successfully created with the same `request_id`. See [Retry a transfer](/payouts__manage-payouts__handle-failed-payouts#retry-a-payout).  | `payment.retried`| Track the new transfer created. Corresponding fees may apply (see [Fees in retries](/payouts__manage-payouts__handle-failed-payouts#fees-in-retries--3)). |
| CANCELLATION_REQUESTED   | Transfer cancellation has been requested before `DISPATCHED`, and will transition to `CANCELLED` when the currency conversion (if any) is settled. | `payment.cancellation_requested`| No action needed. |
| CANCELLED   | The transfer has been successfully cancelled. The transfer amount (less any applicable fees) will be returned to the Wallet. See [Cancel a transfer](/payouts__manage-payouts__handle-failed-payouts#cancel-a-payout) for further details.  | `payment.cancelled`| Corresponding fees may apply (see [Fees in cancellations](/payouts__manage-payouts__handle-failed-payouts#fees-in-cancellations--3)). |
| SUSPENDED   | The transfer has been suspended after being reviewed by Airwallex. It will be cancelled by us usually within a week, at which point its status will transition to `CANCELLED`. | `payment.suspended` | Expect the transfer to be automatically cancelled by Airwallex. |

\* These statuses are only applicable to the transfers that are [created and submitted for approval](/payouts__manage-payouts__manage-approvals-for-payouts).

You can subscribe to [Transfers webhook events](/developer-tools__listen-for-webhook-events__event-types__payouts) to receive the transfer information in JSON payloads in case of any status transitions. 

This page applies for __API version 2023-10-01 or earlier__.


After a transfer has been `DISPATCHED`, it may fail our banking partner’s processing or be rejected by the recipient bank, at which point its status will transition to `FAILED`. Subscribe to `payment.failed` [webhook events](/developer-tools__listen-for-webhook-events__event-types__payouts) to receive real-time notifications of each transfer's failure, and retrieve failure reasonses by calling [Get payment by ID](/api#/Payouts/Payments/_api_v1_payments__payment_id_/get) or [Get list of payments](/api#/Payouts/Payments/_api_v1_payments/get). 

See [Failure reasons](/payouts__manage-payouts__failure-reasons) for all possible failures and recommended actions. Please note that failed transfers will be automatically cancelled after a certain time depending on the region you are in. Please reach out to your Account Manager to find out more. 

There are 2 options to handle a failed transfer:
- __Retry a transfer__. If a transfer failed due to incorrect beneficiary details (failure code`901XX`-`904XX`, see [Failure reasons](/payouts__manage-payouts__failure-reasons)), you can retry it by calling [Retry a payment](/api#/Payouts/Payments/_api_v1_payments_retry__payment_id_/post) with the updated parameters. Please refer to [Retry a transfer](/payouts__manage-payouts__handle-failed-payouts#retry-a-payout) below for more details.
- __Cancel a transfer__. If a transfer failed due to reasons other than incorrect beneficiary details (failure code`905XX`-`999XX`, see [Failure reasons](/payouts__manage-payouts__failure-reasons)), or if you would like to amend transfer request parameters other than beneficiary details, you can cancel it by calling [Cancel a payment](/api#/Payouts/Payments/_api_v1_payments_cancel__payment_id_/post). Please refer to [Cancel a transfer](/payouts__manage-payouts__handle-failed-payouts#cancel-a-payout) below for more details.

The following table provides guidance on the rules and behaviors subsequent to these actions.

|           | Retry a transfer    | Cancel a transfer    |
| --------- | ------------------| ------------------ |
| __Behavior__      | The status of the failed transfer transitions to `RETRIED`, while a new transfer with a different `payment_id` will be created automatically upon successful retry. | The status of the failed transfer will transition to `CANCELLED`. You may choose to create a new transfer by calling [Create a new payment](/api#/Payouts/Payments/_api_v1_payments_create/post). |
| __Refund__                  | No refund to your Wallet. Transfer amount will be immediately used for the new transfer created upon successful retry.  | Transfer amount (less any applicable fees) will be refunded to your Wallet. You can retrieve the updated Wallet balance via [Get current balances](/api#/Core_Resources/Balances/_api_v1_balances_current/get). |
| __Currency conversion__     | No additional conversion because the refunded transfer amount is immediately used for the new transfer.  | Transfer amount (less any applicable fees) will be refunded to your Wallet in the payment currency. For certain exotics currencies that cannot be held in the Wallet, the funds will be adjusted back in the source currency. See [Currency conversion in cancellations](/payouts__manage-payouts__handle-failed-payouts#currency-conversion-in-cancellations--3). |
| __Fees__        | Transfer fee for the failed transfer will not be refunded. Transfer fee for the new transfer and third-party fee (if any) for the failed transfer will be separately deducted from your Wallet 5 business days after retry. See [Fees in retries](/payouts__manage-payouts__handle-failed-payouts#fees-in-retries--3). | Transfer fee for the failed transfer will not be refunded. Third-party fee (if any) for the failed transfer will be separately deducted from your Wallet 5 business days after cancellation. See [Fees in cancellations](/payouts__manage-payouts__handle-failed-payouts#fees-in-cancellations--3).  |

Retry a transfer

Cancel a transfer

This page describes transfer webhooks for legacy API versions. For the latest version, please see [transfer webhooks](/developer-tools__listen-for-webhook-events__event-types__transfers).

API ver. 2024-01-31 to 2024-08-07

API ver. 2023-10-01 and before

This page lists all the possible error code values before __API version 2024-01-31__ and error response structures before __API version 2024-09-27__.

For 400 errors, the response you receive will contain a `code` specifying the error encountered. Depending on whether it is a general error or a field validation error, it may contain a `params` object or an `errors` object with additional parsable information which helps you handle exceptions systematically.

## General errors with example response

A general error provides a response where `code` is not `validation_failed`. Like in the example below, an error response could contain a `params` object with additional parsable information, e.g. related `payment_id`. 

```json
{
     "code": "request_id_duplicate",
     "params": { 
         "payment_id": "f26e4e6f-16cd-4723-8112-1cf76eec92e1" 
      }
}
```

See [400 errors](/payouts__error-codes#400-errors) for all potential error codes and descriptions, organized by corresponding Transfers & Beneficiaries API endpoints. For errors with transfers to Airwallex accounts specifically, please see [Errors for transfers to Airwallex accounts](/payouts__error-codes#errors-for-payouts-to-airwallex-accounts).

## Field validation errors with example response

A field validation error provides a response where `code` is `validation_failed`. This means that the request has failed schema validation. Like in the example below, the response contains an `errors` object with:
- `source`: The specific field within the request that has failed schema validation.
- `code`: Unique numeric identifier of the specific validation error encountered.
- `params`: Additional parsable information relating to the specific validation error where applicable, e.g. minimum and maximum character length.

```json
{
    "code": "validation_failed",
    "errors": [
        {
            "source": "beneficiary.address.postcode",
            "code": "030"
        },
        {
             "source": "beneficiary.address.street_address",
             "code": "018",
             "params": { 
                  "length_min": 5,
                  "length_max": 200
              }
        }
    ]
}

```

See [Field validation errors](/payouts__error-codes#field-validation-errors) to learn about all possible codes and applicable parameters. For errors with transfers to Airwallex accounts specifically, please see [Errors for transfers to Airwallex accounts](/payouts__error-codes#errors-for-payouts-to-airwallex-accounts).

400 errors

Field validation errors

Errors for transfers to an Airwallex account

As we continue to improve our Transfers product, we highly recommend that you integrate to the __latest API version__ to enjoy our new features and capabilities.

Starting from __API version 2024-01-31__, we have released major upgrades to the transfer funding and refund behaviors, which also introduced a new set of transfer status definitions and transitioning experience. For the behaviors on __older API versions__, please refer to the subpages under this section.

You can also refer to our [API reference](/api#/Payouts/Payments/Intro) for the full technical documentations of all historical API versions.

docsLogo

Bacs Direct Debit - BETA

Bancontact

BLIK

Estonian Banks

iDEAL

Latvian Banks

Lithuanian Banks

Maxima

MyBank

Multibanco

Narvesen

Pay by Bank app (PbBa)

Paysafecard

Paysafecash

Paysera

PayU

Perlas Terminals

Przelewy24 | P24

Satispay

SEPA Direct Debit - BETA

Sofort.

Trustly

TWINT - BETA

EU & UK

Desktop/Mobile Website Browser - TWINT

US tax reporting

Desktop/Mobile Website Browser - Klarna

Embedded Tax Form component

Desktop/Mobile Website Browser

Store Detail Requirement 

Payment Method List

Native API

Configure remote authorization

iOS SDK

Android SDK

Registered user checkout

Install the Airwallex Google Pay Payments App

Getting Started

Install Airwallex Card Payments app

Install Airwallex Online Payments App

Install Airwallex Klarna Payments App

Install Airwallex Afterpay Payments App

Install the Airwallex Apple Pay Payments App

Shopline

Supported currencies

 Micro-deposit verification

Desktop/Mobile Website Browser - Afterpay / Clearpay

Afterpay / Clearpay

Pakistan

Bangladesh

Indonesia

Market & infrastructure coverage

Settlement report

Transaction & fee types

Payment activity export

Payments rounding logic

Reporting

Enable Native Credit/Debit Cards

Hungary

Zambia

Wallis and Futuna

Virgin Islands (British)

Viet Nam

Vanuatu

Uzbekistan

Uruguay

United States

United Kingdom

United Arab Emirates

Ukraine

Uganda

Turkey

Tunisia

Togo

Timor-Leste

Thailand

Tanzania, United Republic of

Tajikistan

Taiwan (China)

Switzerland

Sweden

Sri Lanka

Spain

South Africa

Slovenia

Slovakia

Singapore

Seychelles

Serbia

Senegal

Saudi Arabia

San Marino

Saint Pierre and Miquelon

Saint Martin (French part)

Saint Lucia

Saint Barthélemy

Rwanda

Romania

Réunion

Republic of the Congo

Qatar

Puerto Rico

Portugal

Poland

Philippines

Peru

Paraguay

Panama

Palestine, State of

Oman

Norway

Nigeria

Niger

New Zealand

New Caledonia

Netherlands

Nepal

Namibia

Morocco

Montenegro

Albania

Algeria

Andorra

Angola

Anguilla

Antigua and Barbuda

Argentina

Armenia

Aruba

Australia

Austria

Azerbaijan

Bahrain

Belgium

Belize

Benin

Bolivia

Bosnia and Herzegovina

Botswana

Brazil

Bulgaria

Burkina Faso

Cambodia

Cameroon

Canada

Canary Islands

Central African Republic

Chad

Chile

China

Colombia

Costa Rica

Côte d'Ivoire

Croatia

Curaçao

Cyprus

Czech Republic

Denmark

Dominican Republic

Dominica

Ecuador

Egypt

El Salvador

Equatorial Guinea

Estonia

Faroe Islands

Fiji

Finland

France

French Guiana

French Polynesia

French Southern Territories

Gabon

Payout network