Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Back to home
OverviewHow Transactional FX worksSupported regions and currenciesFunding and settlement models
Use Cases
Get started
Choose your FX solution
Create a conversion
Conversion statuses
Conversion variations
Troubleshooting
Test and go live

Create a conversion

Use this step-by-step guide to learn how to successfully create currency conversions for your Airwallex Wallet currencies using Transactional FX APIs. Depending on your chosen FX solution, MarketFX or LockFX, the integration code for the first two steps will differ.

For conversions during payouts, see Create a payout.

Before you begin

Step 1: Retrieve a quote

Regardless of the FX product, you can retrieve price quotes before booking a conversion.

MarketFX

If you are using MarketFX, you can retrieve an indicative quote for a specified currency pair that will give you an indication of the current price you would receive if you were to create a currency conversion.

Call Retrieve an indicative MarketFX quote API with the buy_currency, sell_currency, and either the sell_amount or buy_amount as query parameters. You can optionally specify a conversion_date, i.e., the date on which the conversion will be settled. If you do not specify a date, Airwallex determines the default based on your funding mode (see settlement timing).

Example request

Shell

Example response

JSON

LockFX

If you are using LockFX, call Create a LockFX quote API to retrieve a guaranteed conversion rate for use within the validity period. Specify the buy_currency, sell_currency, buy_amount/sell_amount, and the quote validity. The validity period you specify must belong to the validity group configured for your account. See Quote validity period.

Optionally, you can specify a conversion_date, i.e., the date on which the conversion will be settled. If you do not specify a date, Airwallex determines the default based on your funding mode (see settlement timing).

Example request

Shell

A successful conversion returns the quote_id in the response. You must store the quote_id for future use on subsequent conversions or payout requests (see Create a payout).

The quote response also contains key details that are required for a successful subsequent conversion booking including:

  • Validity period of the quote ( valid_from , valid_to )
  • Whether the quote can be used once or multiple times (MULTI_USE or SINGLE_USE)
  • Conversion date (conversion_date)
  • Direction of conversion (buy_currency, sell_currency)

Example response

JSON

Step 2: Book a conversion

Call Create a conversion API to execute a conversion.

As a MarketFX customer, you do not need to populate quote_id so leave this field blank to allow Airwallex to execute MarketFX conversion.

When using LockFX, you must use a valid quote_id in the conversion or payout request. The relevant details from the quote including buy_currency, sell_currency and any future dated conversion_date if specified must match the subsequent conversion or payout request. A successful conversion request will occur at the client_rate from your retrieved quote.

Example request

Shell

Example response

JSON

Step 3: Retrieve the conversion

You can retrieve details of a previous conversion including its current status anytime using Retrieve a conversion API. If you want to retrieve details of all conversions associated with your account, see List all conversions API.

See Conversion statuses to learn about the status of your conversion.

Example request

Shell

Example response

JSON
On this page