Transactional FX

Airwallex FX provides a wide ranging set of solutions to allow businesses to access FX prices and execution services in a way that meets the needs and workflows of your business. Each business is unique and the challenges involved with converting one currency to another will also vary from business to business.

The Airwallex solution to these challenges is to offer great flexibility in the way you obtain prices from us, the way you execute transactions with us and the ways that you can manage any inherent FX risk your business is exposed to.

Our two primary products, MarketFX and LockFX, will allow each business to integrate with the solution that best meets the unique needs of each business. Both products are designed to work closely alongside the wider Airwallex range of features.

How to access

Create your Airwallex account by submitting your business information via the online sign up form or by contacting us directly. Once your account is activated, you will immediately be able to start transacting FX with Airwallex via the Airwallex Web App. Details on how to start transacting via the Airwallex Web App can be found in the Quickstart section of this Product documentation.

If you wish to integrate against the Airwallex API , including AirwallexScale , integration can begin immediately following registration success. One of our integration managers will be on hand to guide you through the process of integration, including resolving any queries and helping with testing.

When you're ready to begin, you can make your way to our Quickstart guide to get your integration up and running quickly with our series of sample code snippets.

MarketFX Overview

MarketFX allows for clients to simply request to be executed at the prevailing market rate via one of our panel of global liquidity providers.

This model will be the best fit for clients who are highly transactional and need to be booking many transactions in a short period of time without concern for FX market risk. They may be managing FX market risk themselves, or be less sensitive to FX market risk. They are typically seeking only to be booked at the rate closest to current market prices at the time of execution and need guaranteed execution regardless of market conditions.

Typical use cases for MarketFX

  • A marketplace platform that has a high number of cross-border transactions
  • A business looking to transact larger single ticket sizes at a price as close to market rates as possible

Eagle Electronics

Eagle Electronics is an online retailer based in the United Kingdom. They have operations in multiple jurisdictions around the world where consumers purchase electronic goods primarily via card in each of those jurisdictions.

Eagle Electronics has decided that whenever a customer makes a purchase in a foreign jurisdiction on card, they would like to book an FX transaction immediately at the rate closest to market to clear that risk back to GBP.

Eagle Electronics integrates with Airwallex’s MarketFX product giving them access to book transactions at market quickly and easily.

They have static prices in each of the regions they operate, and have currently priced a set of headphones in France at EUR140.00.

Customers will see and purchase the headphones at EUR140.00 throughout the day, week or more and following the acceptance of the card Eagle Electronics will send a conversion request to Airwallex to sell EUR and buy GBP. The amount of GBP they receive will be dependent on the market rate at the time of booking, for example if the EURGBP rate returned on the conversion request was 0.8625, they would receive GBP120.75 - they also have a treasury team that is monitoring and managing FX market risk separately to the underlying commercial transaction.

MarketFX transaction flow

The MarketFX transaction flow can be broken down into its component parts - not all clients will need or want to retrieve an indicative price before placing a conversion request, or payment request with underlying conversion.

For those that do, you will be able to either see an indicative price displayed on the Airwallex Web App when entering details of the transaction, or you can call the indicative price endpoint via the client API.

Following retrieval of the indicative price, you can choose to book a conversion request. Depending on market conditions, and the amount of time you wait between calling for the indicative price and requesting a conversion will determine how much variance there is between the price you get executed at, and the indicative rate initially returned.

MarketFX pricing

Airwallex has integrated with several global and regional banks that provide liquidity in both freely traded pairs and in currencies with additional capital controls. Our proprietary MarketFX pricing engine blends prices from across our panel of banks to generate highly available and stable FX prices accessible by clients 24 hours a day, 7 days a week.

Airwallex’s MarketFX pricing algorithm is designed to deliver the best possible price to clients at the time of execution, taking into account a wide variety of factors which may include, but not limited to, current market volatility, available liquidity in the market, the size of the transaction and the selected date you wish to settle the transaction. Any additional agreed margin will be applied on top of the price produced by our MarketFX pricing engine.

LockFX Overview

LockFX allows for clients to integrate with Airwallex in a more flexible manner, to ensure that the business is better able to manage any FX market risk arising from their specific workflows.

The LockFX solution is best suited to businesses that have cross-border transactions, but want to integrate a solution that removes any risk of the FX price moving between the time the business conducts a transaction with one of their own customers and the time at which they convert that revenue to repatriate that revenue back to their home domicile.

Typical use cases for LockFX

  • A marketplace platform with many consumers interacting with many merchants
  • A single user wanting to have absolute certainty on the rate they will be executed at when executing a transaction
  • Businesses with workflows that require manual intervention, for example, internal 2-step approvals on transactions

ABC Airways (Short validity periods, single-use quotes)

ABC Airways is an airline domiciled in Singapore with operations in Australia. They have made a decision to pass dynamic pricing onto their customers that fluctuate with underlying foreign currency price movements.

ABC Airways knows that it takes their Australian customers less than 10 mins to complete the booking of a flight from Australia to Singapore. They integrate with Airwallex’s LockFX product, giving them access to prices for AUDSGD valid for 15 minutes.

Today, they have priced the flight from Australia to Singapore at SGD1,000.00 for an economy class seat.

When Customer A begins to the booking process at 11:00am, ABC Airways request a quote from Airwallex, and a quote of 0.9679 is returned. Using this quote, Customer A is shown a price of AUD1,033.16 for the flight.

5 minutes later, at 11:05am, Customer B begins the booking price for the same flight. Again ABC Airways request a quote from Airwallex, but due to market movement this time a quote of 0.9681 is returned. Using this quote Customer B is shown a price of AUD1,032.95.

Assuming both Customer A and Customer B complete the booking process, ABC Airways would use the retrieved quote IDs against the respective conversion requests to ensure they receive SGD1,000.00 for both flights as expected.

XYZ eComm (long validity periods, multi-use quotes)

XYZ eComm is an eCommerce platform based in Hong Kong with a presence in the United States. They have noted consumer behaviours on their platform that shows a consumer visiting the site multiple times throughout the day before making a purchase towards the end of the day.

As a result, they are seeking more static pricing during the day so that the consumers are shown the same price in USD if they visit in the morning as when they visit again in the afternoon.

XYZ eComm integrates with Airwallex’s LockFx product, which gives them access to prices for USDHKD for 24 hours. They request a quote from Airwallex, and a quote of 7.8424 is returned. They use this quote across the platform to price all goods available for sale in USD to customers based in the United States.

Today they have priced one of their items, a winter jacket, at HKD600.00 which will then be shown in the United States as USD76.51 when customers look to buy the jacket.

This has the benefit to the platform, and the consumer as a result of seeing the same price for the goods during the course of the day.

For every consumer that buys the jacket through the day, the consumer will pay USD76.51 and XYZ eComm will receive HKD600.00 as long as XYZ eComm sends a conversion request to Airwallex using the quote ID on each consumer purchase.

LockFX variations

Working closely with your dedicated integration manager, the following LockFX variations can be applied to your account so that the best balance can be struck for your business between cost, speed and matching of commercial workflows to the pricing and execution flow selected.

Quote validity length

Airwallex is able to support quote validity lengths of:

  • 1 minute
  • 15 minutes
  • 30 minutes
  • 1 hour
  • 4 hour
  • 8 hour
  • 24 hour

The default configuration on newly opened Airwallex accounts are validity lengths from the Short group below. In the event your workflows are better suited to longer validity periods, your integration manager will help to assign your account to a group with longer validty lengths.

GroupQuote Validity Lengths
Short (Default)1 minute, 15 minutes, 30 minutes
Medium30 minutes, 1 hour, 4 hours
Long4 hours, 8 hours, 24 hours

Quote usage

LockFX allows for quotes to be used either multiple times for execution (multi-use), or just once (single-use default) depending on how your account is set-up. This variation will change how you retrieve quotes from Airwallex and use them to execute transactions.

Refunds

Some clients may have a requirement to initiate a refund, or a reversal of a previously booked and settled transaction at the original rates. Clients looking to access Refunds on their account will need to work closely with their integration manager to understand the volume of expected refunds, and how long following a transaction a refund can be requested, to ensure the best possible pricing can be provided to you.

Refunds can be requested by sending a refund request to the client API quoting the conversion_id of the previously booked and settled conversion you would like a refund on. This will trigger a conversion to be created in the inverse direction of the original conversion. This conversion will need to be funded like any other booked conversion.

Changing variations

If you wish to change any of the LockFX variations assigned to your account, you will need to contact your integration manager to guide through the process and advise of any changes required to your integration.

LockFX transaction flow

The LockFX transaction flow requires obtaining a price quote prior to requesting a conversion. Following retrieval of a price quote, the quote ID will need to be passed to Airwallex alongside a subsequent conversion request.

The outcome of obtaining a quote will be that the price returned to you on the quote will be guaranteed for the length of the validity period requested, regardless of ongoing market price movements. This allows for certainty in the rate at which you will be executed while users on your platform continue with your existing workflows to book or purchase goods or services.

LockFX pricing

LockFX pricing continues to build on the price produced by the MarketFX pricing engine. Further adjustments are made to the price to take into consideration factors including:

  • The validity length of the requested quote;
  • Whether the quote requested is valid for multi-use or single-use
  • The refund variables assigned against your account (if any)

The integration manager working with you on the integration can guide you through the optimal set-up in LockFX variations to meet your business requirements at the lowest FX cost.

Transacting FX with Airwallex

Airwallex Web App QuickStart

When transacting foreign exchange with Airwallex through the Web App, only MarketFX is currently available via the conversion form. An indicative rate is displayed on the form and is periodically refreshed to given you an indication of the current price.

Following the creation of a currency conversion, the funds will be made available to you in your Airwallex account for subsequent payout or use based on the conversion date selected.

Airwallex Client API QuickStart

You can make use of the Airwallex Client API to transact foreign exchange using either the MarketFX or LockFX solutions. The following step-by-step instructions can guide you to the simplest way of integrating and getting started transacting with Airwallex in the shortest possible time.

MarketFX quickstart

Step 1: Retrieve indicative quote

If you are making use of the MarketFX product, 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.

Sample Code

curl -X GET \  'http://api-demo.airwallex.com/api/v1/quotes/market?buy_currency=EUR&sell_currency=USD&buy_amount=500.00&conversion_date=2019-05-20' \
  -H 'Authorization: Bearer <token>'

Response

{
    "awx_rate": 1.118012,
    "buy_amount": 500,
    "buy_currency": "EUR",
    "client_rate": 1.119097,
    "sell_amount": 559.55,
    "sell_currency": "USD",
    "conversion_date": "2019-05-21",
    "currency_pair": "EURUSD",
    "dealt_currency": "EUR",
    "settlement_cutoff_time": "2019-05-20T09:00:00+0000"
}

Step 2: Request currency conversion

Regardless of whether you have previously retrieved an indicative quote, when you request a currency conversion it will be executed at the prevailing rate based on market conditions. You do not need to manage quote ids as the request parameters do not allow for an id to be passed.

Sample Code

curl -X POST \
  http://api-demo.airwallex.com/api/v1/conversions/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
  "request_id": "68726c8c-3ffc-4a54-84ea-e2be08598a29",
  "buy_amount": "67.75",
  "buy_currency": "USD",
  "sell_currency": "EUR",
  "conversion_date": "2019-05-17",
  "term_agreement": true
}’

Step 2a: Request payment

An alternative to booking a currency conversion and then requesting payments following the processing of that conversion, you can request a payment with an underlying currency conversion. To trigger an underlying currency conversion in the payment request, the payment_currency should be different to the source_currency. Again the request parameters do not allow for a quote id to be passed and the currency conversion will be booked at the prevailing rate based on market conditions.

Sample Code

curl -X POST \
  http://api-demo.airwallex.com/api/v1/payments/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
  "beneficiary": {
    "address": {
      "country_code": "BE",
      "street_address": "55288 Schiller Plain",
      "city": "Port Irvingberg",
      "state": "Iowa",
      "postcode": "88347-1304"
    },
    "bank_details": {
      "bank_country_code": "AU",
      "account_currency": "AUD",
      "account_number": "11111111",
      "account_routing_type1": "bsb",
      "account_routing_value1": "980302",
      "account_name": "Delta Beahan",
      "bank_name": "White Group"
    },
    "entity_type": "PERSONAL",
    "first_name": "Loma",
    "last_name": "Miller",
    "date_of_birth": "1973-04-23"
  },
  "payment_currency": "AUD",
  "source_currency": "EUR",
  "payer": {
    "entity_type": "PERSONAL",
    "address": {
      "country_code": "SI",
      "street_address": "07874 Upton Squares",
      "city": "Willmouth",
      "state": "New Jersey",
      "postcode": "26641-5666"
    },
    "first_name": "Maida",
    "last_name": "Bales",
    "date_of_birth": "1930-04-23"
  },
  "payment_method": "LOCAL",
  "payment_amount": 261,
  "reference": "client-ref",
  "reason": "personal_remittance",
  "request_id": "a07d02b6-0581-441c-a9b6-2997ee3014f3"
}'

LockFX quickstart

Step 1: Create new quote

The quote you retrieve when you are utilising the LockFX product is an executable price as long as it is used before the end of the validity period and the key details from the quote match the subsequent request.

Sample Code

curl -X POST \
  http://api-demo.airwallex.com/api/v1/quotes/lockfx/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
	"buy_currency" : "HKD",
	"sell_currency" : "USD",
	"buy_amount": 67.75, 
	"conversion_date": "2019-05-21",
	"validity": "MIN_15"
}’

Step 2: Store quote for future use

Once you have retrieved your quote, you will need to store the quote_id for future use on subsequent conversion or payment requests. The quote response also contains key details required to ensure a successful subsequent booking including the valid_from and valid_to fields, whether the quote can be used once or multiple times, conversion_date, and the direction (buy/sell currencies). These key details will be validated against the subsequent converison or payment request.

Response

{
    "quote_id": "995ea163-7652-411d-b37d-ee243c888940",
    "awx_rate": 7.8498,
    "buy_amount": 67.75,
    "buy_currency": "HKD",
    "client_rate": 7.847281,
    "sell_amount": 8.62,
    "sell_currency": "USD",
    "conversion_date": "2019-05-21",
    "currency_pair": "USDHKD",
    "dealt_currency": "HKD",
    "usage": "MULTI_USE",
    "valid_from": "2019-05-20T04:42:19+0000",
    "valid_to": "2019-05-20T04:57:19+0000",
    "validity": "MIN_15"
}

Step 3: Request currency conversion

When using LockFX, you must use a valid quote ID in any conversion or payment request. The relevant details from the quote including buy currency, sell currency and any date if specified must match the subsequent conversion or payment request. A successful conversion request will occur at the client_rate from your retrieved quote.

Sample Code

curl -X POST \
  http://api-demo.airwallex.com/api/v1/conversions/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
  "request_id": "68f9ee78-b065-422e-8329-62305699ed9e",
  "quote_id": "995ea163-7652-411d-b37d-ee243c888940"
  "buy_amount": "67.75",
  "buy_currency": "HKD",
  "sell_currency": "USD",
  "term_agreement": true,
  "conversion_date": "2019-05-21",
}'

Step 3a: Request payment

Alternatively, by specifiying different payment_currency and source_currency parameters when requesting a payment, you will trigger an underlying currency conversion. You will need to ensure:

  1. a valid quote_id is passed in the request;
  2. the client_sell_currency from the quote response matches the source_currency in the payment request; and
  3. the client_buy_currency from the quote response matches the payment_currency in the payment request

Sample Code

curl -X POST \
  http://api-demo.airwallex.com/api/v1/payments/create \
  -H 'Authorization: Bearer <token>' \
  -d '{
  "quote_id": "995ea163-7652-411d-b37d-ee243c888940",
  "request_id": "140ee4b0-18b2-47d9-a823-70ae8f13cb15",
  "beneficiary": {
    "address": {
      "country_code": "BE",
      "street_address": "55288 Schiller Plain",
      "city": "Port Irvingberg",
      "state": "Iowa",
      "postcode": "88347-1304"
    },
    "bank_details": {
      "bank_country_code": "AU",
      "account_currency": "HKD",
      "account_number": "826437792",
      "account_routing_type1": "bsb",
      "account_routing_value1": "980302",
      "account_name": "Delta Beahan",
      "bank_name": "White Group",
      "swift_code": "ACLRAUSS"
    },
    "entity_type": "PERSONAL",
    "first_name": "Loma",
    "last_name": "Miller",
    "date_of_birth": "1973-04-23"
  },
  "payment_currency": "HKD",
  "source_currency": "USD",
  "payment_date": "2019-05-21",
  "payer": {
    "entity_type": "PERSONAL",
    "address": {
      "country_code": "SI",
      "street_address": "07874 Upton Squares",
      "city": "Willmouth",
      "state": "New Jersey",
      "postcode": "26641-5666"
    },
    "first_name": "Maida",
    "last_name": "Tromp",
    "date_of_birth": "1930-04-23"
  },
  "payment_method": "SWIFT",
  "payment_amount": 261,
  "reference": "client-ref",
  "reason": "personal_remittance"
}'

Funding model

Airwallex accounts can be set-up with either a pre-funding requirement, or a post-funding workflow. Depending on the jurisdiction in which you operate from, and the types of accounts you have with us, your account will be assigned one of the following funding models.

Post-funding accounts will have a limit assigned to them, which will be the upper limit of the notional amount of unsettled transactions you can have open with Airwallex at any one time.

Pre-funding accounts will need to have sufficient funds loaded into the account prior to booking a transaction.

Currency Pairs

Airwallex currently has the capability to transact in 138 pairs - a capability that is constantly improving. Some of the pairs are freely traded which means we are able to price and execute on both sides of the trade, whereas pairs that contain a currency with additional constraints are considered exotic currency pairs.

Freely Traded Pairs

The set of freely traded pairs below are those that Airwallex can provide pricing and execute on both ‘sides of the trade’, for example on the pair USDHKD, you can:

  • Sell USD / Buy HKD
  • Sell HKD / Buy USD
AUDCADCHFJPYGBPCADNZDSGD
AUDCHFCHFSGDGBPCHFNZDTHB
AUDCNHCHFTHBGBPCNHNZDUSD
AUDHKDCNHJPYGBPHKDSGDCNH
AUDJPYCNHTHBGBPJPYSGDHKD
AUDNZDEURAUDGBPNZDSGDJPY
AUDSGDEURCADGBPSGDSGDTHB
AUDTHBEURCHFGBPTHBTHBJPY
AUDUSDEURCNHGBPUSDUSDCAD
CADCHFEURGBPHKDCNHUSDCHF
CADCNHEURHKDHKDJPYUSDCNH
CADHKDEURJPYHKDTHBUSDHKD
CADJPYEURNZDNZDCADUSDJPY
CADSGDEURSGDNZDCHFUSDSGD
CADTHBEURTHBNZDCNHUSDTHB
CHFCNHEURUSDNZDHKD
CHFHKDGBPAUDNZDJPY

Exotic Currency Pairs

The exotic pairs typically have constraints that are applied to them, usually due to regulatory regimes in the local jurisdiction of the exotic currency being transacted.

These constraints may include being able to transact on one side of the trade, as follows:

  • Selling USD / Buying MYR

Other constraints may include:

  • The need to tie the conversion to an accompanying payment
  • The provision of additional documentation to support the conversion
  • Limitations on the value date selectable
AUDIDRCNHPHPJPYVNDUSDVND
AUDINRCNHVNDNZDIDRUSDKRW
AUDMYREURIDRNZDINRAUDKRW
AUDPHPEURINRNZDMYREURKRW
AUDVNDEURMYRNZDPHPGBPKRW
CADIDREURPHPNZDVNDNZDKRW
CADINREURVNDSGDIDRCADKRW
CADMYRGBPIDRSGDINRCHFKRW
CADPHPGBPINRSGDMYRSGDKRW
CADVNDGBPMYRSGDPHPTHBKRW
CHFIDRGBPPHPSGDVNDHKDKRW
CHFINRGBPVNDTHBIDRJPYKRW
CHFMYRHKDIDRTHBINRCNYKRW
CHFPHPHKDINRTHBVNDINRJPY
CHFVNDHKDMYRUSDIDRMYRJPY
CNHIDRHKDPHPUSDINRMYRTHB
CNHINRHKDVNDUSDMYRPHPJPY
CNHMYRJPYIDRUSDPHPPHPTHB