Payout statuses (older versions)

Handle failed payouts (older versions)

Payout webhooks (older versions)

Error codes (older versions)

Payouts

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 payouts on __API version 2023-10-01 or earlier__.

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

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

![payout 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 payout 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 payout is submitted for approval. | `payment.in_approval` | Approvers can review the payout in the web app. | 
| RECALLED* | The payout is recalled by a user in the web app. | `payment.recalled` | Users can edit and resubmit the payout in the web app.| 
| REJECTED* | The payout is rejected by an approver in the web app. | `payment.rejected` | Users can edit and resubmit the payout in the web app.| 
| BLOCKED* | Payout is blocked as next approver cannot be found | `payment.blocked` | Account owner or Admin users can edit the Transfers approval workflow and resubmit the payout in the web app. | 
| PENDING_FUNDS* | Payout is waiting for funds to be available. | `payment.pending_funds` | No action needed. | 
| IN_REVIEW    | The payout is on hold and being reviewed by Airwallex. We may request for additional information from you via email. Once the review is completed, the payout will automatically transition to `READY_FOR_DISPATCH`. If the payout 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 payout 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 payout has been dispatched from Airwallex and will remain in this status if successful. Note that payouts 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 payout has failed our banking partner's processing or was rejected by the recipient bank. Failed payouts 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 payout 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 payouts](/payouts__manage-payouts__handle-failed-payouts) to determine the next step based on your failure reason.|
| RETRIED   | The failed payout has been retried with updated details. The `RETRIED` status is the end state for the original payout, and a new payout is successfully created with the same `request_id`. See [Retry a payout](/payouts__manage-payouts__handle-failed-payouts#retry-a-payout).  | `payment.retried`| Track the new payout created. Corresponding fees may apply (see [Fees in retries](/payouts__manage-payouts__handle-failed-payouts#fees-in-retries--3)). |
| CANCELLATION_REQUESTED   | Payout 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 payout has been successfully cancelled. The payout amount (less any applicable fees) will be returned to the Wallet. See [Cancel a payout](/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 payout 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 payout to be automatically cancelled by Airwallex. |

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

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

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


After a payout 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 payout'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 payouts 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 payout:
- __Retry a payout__. If a payout 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 payout](/payouts__manage-payouts__handle-failed-payouts#retry-a-payout) below for more details.
- __Cancel a payout__. If a payout 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 payout 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 payout](/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 payout    | Cancel a payout    |
| --------- | ------------------| ------------------ |
| __Behavior__      | The status of the failed payout transitions to `RETRIED`, while a new payout with a different `payment_id` will be created automatically upon successful retry. | The status of the failed payout will transition to `CANCELLED`. You may choose to create a new payout by calling [Create a new payment](/api#/Payouts/Payments/_api_v1_payments_create/post). |
| __Refund__                  | No refund to your Wallet. Payout amount will be immediately used for the new payout created upon successful retry.  | Payout 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 payout amount is immediately used for the new payout.  | Payout 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__        | Payout fee for the failed payout will not be refunded. Payout fee for the new payout and third-party fee (if any) for the failed payout 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). | Payout fee for the failed payout will not be refunded. Third-party fee (if any) for the failed payout 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 payout

Cancel a payout

Payout

Payout to an Airwallex account

This page lists all the possible errors associated with the HTTP 400 status code while creating/managing payouts and beneficiaries on __API version 2023-10-01 or earlier__.

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 Payouts & Beneficiaries API endpoints. For errors with payouts to Airwallex accounts specifically, please see [Errors for payouts 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 payouts to Airwallex accounts specifically, please see [Errors for payouts to Airwallex accounts](/payouts__error-codes#errors-for-payouts-to-airwallex-accounts).

400 errors

Field validation errors

Errors for payouts to an Airwallex account

As we continue to improve our Payouts 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 payout funding and refund behaviors, which also introduced a new set of payout status definitions and transitioning experience. For the behaviors on __older verisons (2023-10-01 or earlier)__, 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

 Desktop/Mobile Website Browser

 Save bank details for future payments

 Micro-deposit verification

 EFT Pre-Authorized Debit - BETA

Embedded KYC RFI component

Hosted KYC RFI flow

Native KYC RFI API

Handle KYC RFI

Handle KYC Request for Information (RFI)

Hosted Transaction RFI flow

Embedded Transaction RFI component

Native Transaction RFI API

Handle Transaction RFI

Handle Transaction Request for Information (RFI)

RFI (Request for Information)

Native Cardholder RFI API

Handle Cardholder RFI

Handle Cardholder Request for Information (RFI)

Cardholder types

Cardholder statuses

Create cardholders

Desktop/Mobile Website Browser - Klarna

Dispute Management - Klarna

Extra Merchant Data (EMD) - Klarna

Klarna

Dispute Flow

Handling Disputes

Dispute Notifications

Pay with QR Code (Desktop Website Browser) - WeChat Pay

Mobile App - WeChat Pay 

WeChat Official Account - WeChat Pay

WeChat Mini Program - WeChat Pay

Mobile Browser (H5) - WeChat Pay

Customs Declaration - WeChat Pay

Funds Split - WeChat Pay

WeChat Pay

Refunds

Funds reconciliation

Pay with QR Code (Desktop Website Browser) - Touch 'n Go

Mobile Website Browser - Touch 'n Go

Mobile App - Touch 'n Go

Touch 'n Go

Pay with QR Code (Desktop Website Browser) - Rabbit LINE Pay

Mobile Website Browser - Rabbit LINE Pay

Mobile App - Rabbit Line Pay

Rabbit LINE Pay

Pay with QR Code (Desktop Website Browser) - GCash

Mobile Website Browser - GCash

Mobile App - GCash

GCash

Pay with QR Code (Desktop Website Browser) - DANA

Mobile Website Browser - DANA

Mobile App - DANA

DANA

Pay with QR Code (Desktop Website Browser) - TrueMoney

Mobile Website Browser - TrueMoney

Mobile App - TrueMoney

TrueMoney

Pay with QR Code (Desktop Website Browser) - Kakao Pay

Mobile Website Browser - Kakao Pay

Mobile App - Kakao Pay

Kakao Pay

Mobile App - Alipay CN

Mobile Website Browser - Alipay CN

Mini Program - Alipay CN

Customs Declaration - Alipay CN

Pay with QR Code (Desktop Website Browser) - Alipay CN

Alipay CN

Mobile App - Alipay HK

Mobile Website Browser - Alipay HK

Pay with QR Code (Desktop Website Browser) - Alipay HK

Alipay HK

Transaction failure reasons

Physical and digital cards (older API versions)

Create individual cards (older API versions)

Card statuses

Create a card (older API versions)

Physical and digital cards

Create commercial cards

Create consumer cards

Whitelabel card offering

Create cards

Choose your issuing solution

Supported card programs

3D Secure authentication

Fund your issuing balance (older API versions)

Choose your issuing solution (older API versions)

Supported card types (older API versions)

Secure iframes

Retrieve sensitive card details

Fund your issuing balance

Platform issuing infrastructure for businesses

Consumer payouts via cards

Batch transfers

Payout statuses

Generate a confirmation letter

Simulate payout status transition

Create a payout

 Payout error codes

Batch transfer error codes

Manage approvals for batch transfers

Manage batch transfers

Retrieve batch transfers

Batch transfer statuses

Create a batch transfer

Issuing

Powerful and flexible APIs to programmatically manage your money

Core API

APIs and components to build your own global financial products

Embedded Finance

Accept one-time and recurring payments, with like-for-like settlement for multiple currencies

PaymentsActive

PaymentsNormal

Accept payments from your customers around the world with cards and 160+ alternative payment methods. 

Overview

Payments

Choose your payments solution

Get started with payments

Online payments

Payment Links

Invoice integrations

Manage payments

Payment methods

Test and go live

Troubleshooting

Access interbank FX rates and intelligently manage currency risk

FXActive

FXNormal

Access interbank FX rates and programmatically manage currency risk.

Transactional FX

How Transactional FX works

Supported regions and currencies

Funding and settlement models

Use Cases

Get started

Amendments

Programmatically make cost effective, fast and secure global payouts 

PayoutsActive

PayoutsNormal

Programmatically make cost-effective, fast and secure payouts across the globe.

How Airwallex Payouts work

Payout network

Use cases

Beneficiaries

Payers

Errors

Older API versions

Issue and manage multi-currency cards at scale, while reducing international transaction and FX fees

IssuingActive

IssuingNormal

Issue and manage multi-currency cards at scale, while reducing international transaction and FX fees.

How Airwallex Issuing works

Manage cards

Card controls

Transactions

Older Issuing APIs

Enable your customers to collect, store, and disburse funds globally

GTActive

GTNormal

Enable your customers to collect, store, and disburse funds worldwide using Airwallex's powerful global treasury infrastructure.