Conversion statuses (legacy API versions)

Error codes (legacy API versions)

Conversion variations (legacy API versions)

Conversion webhooks (legacy API versions)

Conversions

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 applies for __API version 2024-06-14 or earlier__.

Conversions have different status types and state transitions. There are two types of status: Intermediate (transition) and Terminal (final).

![FX legacy status](//images.ctfassets.net/c3n7jozh84hr/4YNKeKmV143eX4cIVN7fAb/afe1ebcca7c165b804e6ba98d39e066a/image.png)


| STATUS     | DESCRIPTION     | EMITTED WEBHOOK    | NEXT STEPS     |
| ---------- | ---------- | ---------- | ---------- |
| `AWAITING_FUNDS`       | Intermediate status. Conversion booked successfully, and waiting for client funds. Post-fund pending deduction state.       | `conversion.awaiting_funds`       | On the settlement date, if there are sufficient funds in sell currency, the conversion will transition to `PENDING_SETTLEMENT` and then be immediately `SETTLED`.
You can cancel (`CANCELLED`) unsettled conversions using the [Create an amendment](/api#/Transactional_FX/Conversion_Amendments/_api_v1_fx_conversion_amendments_create/post) API . See [Funding and settlement models](/transactional-fx__funding-and-settlement-models) for more information.       |
| `PENDING_SETTLEMENT`      | Intermediate status. Conversion is processing. Pre-fund future-dated conversions pending settlement state.       | `conversion.pending_settlement`	       | On the settlement date, the conversion will transition to `SETTLED`. You can cancel (`CANCELLED`) unsettled conversions using the [Create an amendment](/api#/Transactional_FX/Conversion_Amendments/_api_v1_fx_conversion_amendments_create/post) API. See [Funding and settlement models](/transactional-fx__funding-and-settlement-models) for more information.      |
| `CANCELLED`       | Terminal status. Conversion cancelled. Funds returned to client wallet.	| `conversion.cancelled`       | No action needed.    |
| `SETTLED`       | Terminal status. Funds have been settled in the wallet.	       | `conversion.settled`       | No action needed.       |
| `ROLLOVER_REQUESTED`       | Deprecated       | `conversion.rollover_requested`       | N/A       |
| `PENDING_ROLLOVER`       | Deprecated       | `conversion.pending_rollover`       | N/A       |

This page lists all the possible errors associated with the HTTP 400 status code while creating/managing conversions and conversion amendments via our API endpoints.

For 400 errors, the response you receive will contain a `code` specifying the error encountered, `message` about the error, and `source` providing additional context about the error.

## General errors with example response

A general error provides an error response with `code`, `message`, `source`. Like in the example below, the response contains an errors object with:
- `code`: Unique numeric identifier of the specific validation error encountered.
- `message`: A message about the specific error encountered.
- `source`: The specific field or object within the request that has failed.
- `details`: Additional details about the request. Generally includes error code trace ID (`correlation_id`) for Airwallex debugging.

__Example:__
```json
{
   "code": "amount_above_limit",
   "message": "Buy amount above the limit of USD 5000000 equivalent",
   "source": "buyCurrency"
}
```

__Example with details:__
```json
{
   "code": "account_not_authorized",
   "details": [
       {
           "code": "correlation_id",
           "message": "26eebb32-36a8-4764-a2af-9621426b1aa4"
       }
   ],
   "message": "account not authorised [POST_TX_CREATION]",
   "source": "account"
}
```

See below for all potential error codes and descriptions, organized by corresponding [Conversion](/api#/Transactional_FX/Conversion/Intro) & [Conversion Amendments](/api#/Transactional_FX/Conversion_Amendments/Intro)  endpoints.

Conversion errors

MarketFX and LockFX errors

Conversion amendments errors

Conversion variations only apply to __LockFX__.

You can apply the following conversion variations to your account to strike the right balance between __cost__, __speed__ and __matching of commercial workflows__ to the pricing and execution flow selected. Contact your Airwallex Account Manager to add/update any of these variations to your account. 

Quote validity period

Quote usage

| Web app Label                     | Event Type                     | Description                                                   |
| -------------------------------- | ------------------------------ | ------------------------------------------------------------- |
| Conversion -> Awaiting funds     | conversion.awaiting\_funds     | Conversion booked successfully, and waiting for client funds. |
| Conversion -> Pending settlement | conversion.pending\_settlement | Conversion is processing                                      |
| Conversion -> Settled            | conversion.settled             | Funds have been settled in the wallet.                        |
| Conversion -> Pending rollover   | conversion.pending\_rollover   | Conversion is pending for rollover.                           |
| Conversion -> Rollover requested | conversion.rollover\_requested | Conversion is requested for rollover.                         |
| Conversion -> Cancelled          | conversion.cancelled           | Conversion cancelled.  Funds returned to client wallet.       |

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

Starting from __API version 2024-06-30__, we have released major upgrades which introduced a new set of Conversion status definitions and transitioning experience. For the behaviours on __older versions (2024-06-14 or earlier)__, please refer to the subpages under this section.

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

docsLogo

Test your custom domain

Remove your custom domain

Set Up your Custom Domain 

Custom Domains (Beta)

 Embedded Beneficiary component

Cards

Whitelisting for payouts SCA compliance

SCA exemptions

Embedded SCA component

SCA for transaction data retrieval

SCA for funds transfers

Strong Customer Authentication (SCA)

Compliance requirements

KYC and onboarding

Handle KYC RFI

Handle KYC Request for Information (RFI)

KYB and onboarding

Handle Payment Enablement RFI

Onboard connected accounts

Native Payment Enablement RFI API

Hosted Payment Enablement RFI flow

Embedded Payment Enablement RFI component

Desktop/Mobile Website Browser

Paysafecash

Paysafecard

Skrill

Maxima

 SPEI - BETA

LinkAja

Jenius Pay

Desktop / Mobile Website Browser

Save bank details for future payments

Micro-deposit verification

SEPA Direct Debit - BETA

Przelewy24 | P24

BLIK

Philippines Online Banking

 Desktop/Mobile Website Browser

 Save bank details for future payments

 Micro-deposit verification

 EFT Pre-Authorized Debit - BETA

Bacs Direct Debit - BETA

Dragonpay

iDEAL

Desktop/Mobile Website Browser 

ACH Direct Debit - BETA

ShopeePay

GrabPay - Malaysia

DuitNow

Boost

E.SUN (Taiwan ATM & Internet banking)

7-Eleven

Atome

Latvian Banks

Perlas Terminals

Thailand Online Banking

Narvesen

Tesco Lotus

Lithuanian Banks

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

Mobile Website Browser - Kakao Pay

Mobile App - Kakao Pay

Kakao Pay

Pay-easy

Konbini

PromptPay

MyBank

Kiosk Payments

PayNow

GrabPay - Singapore

Multibanco

Indonesian Convenience Stores - BETA

Store Detail Requirement 

Embedded KYB component

Native API

Payment Method List

Install the WooCommerce plugin

Error codes

Dispute statuses

Receive dispute updates

Create disputes

Handle transaction disputes

Transaction reconciliation report

Balance activity report

Account statement report

Financial reports

Dispute flow

Enable Apple Pay via web application

Enable Apple Pay using API

Hosted Payment Page

Embedded Elements

Drop-in Element

Mobile SDK

Use your own certificate

Apple Pay

Apple Pay for web

Apple Pay for iOS

Manage Global Accounts

Install the Airwallex Klarna Payments App

Bancontact

Estonian Banks

Pay by Bank app (PbBa)

Paysera

PayU

Satispay

Sofort.

Trustly

EU & UK

Airwallex Pay

Google Pay™

Klarna

Afterpay / Clearpay - BETA

PayPal

Global

Desktop/Mobile Website Browser - Zip

Zip - BETA

Sample integration

Cross-border payroll payouts

Reimbursement payouts funded by the platform's customers

Payment acceptance rate

Desktop/Mobile Website Browser - Afterpay / Clearpay

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

Legacy FX APIs

Programmatically make cost effective, fast and secure global payouts 

PayoutsActive

PayoutsNormal

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

Payouts

How Airwallex Payouts work

Payout network

Use cases

Batch transfers

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.