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.