MarketFX Quickstart

Step 1: Check Balance

Checking the Airwallex Wallet Balance API will allow you to check if you have sufficient funds to complete the conversion immediately.

Sample Request

curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/balances/current' \
--header 'Authorization: Bearer <token>'

Response

 {
    "available_amount": 10000,
    "currency": "USD",
    "pending_amount": 5000,
    "reserved_amount": 0,
    "total_amount": 15000
  },
 {
    "available_amount": 1100,
    "currency": "EUR",
    "pending_amount": 100,
    "reserved_amount": 0,
    "total_amount": 1200
  }

Step 2: Retrieve Indicative Quote

If you are making use of the MarketFX product, you can retrieve an indicative quote API 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 Request

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-21' \
  -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 3: Create a new Conversion

Regardless of whether you have previously retrieved an indicative quote, when you request a currency conversion API 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 Request

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": "500.00",
  "buy_currency": "EUR",
  "sell_currency": "USD",
  "conversion_date": "2019-05-21",
  "term_agreement": true
}’

Step 3a: Create a new Payment

An alternative to booking a currency conversion and then requesting payments following the processing of that conversion, you can request a payment API 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 Request

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"
}'

Step 4: Check Balance

Following a successful conversion, the Airwallex Wallet Balance API will be updated immediately where you have selected to convert today and there were sufficient funds available.

Sample Request

curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/balances/current' \
--header 'Authorization: Bearer <token>'

Response

 {
    "available_amount": 9440.45,
    "currency": "USD",
    "pending_amount": 5000,
    "reserved_amount": 0,
    "total_amount": 14440.45
  },
 {
    "available_amount": 1600,
    "currency": "EUR",
    "pending_amount": 100,
    "reserved_amount": 0,
    "total_amount": 1700
  }

Step 5: Retrieve the previously created Conversion

Previously completed conversions can be retrieved and the current status identified on the response.

Sample Request

curl --request GET \
--url 'https://api-demo.airwallex.com/api/v1/conversions/d9af1614-a6a1-4d45-aae7-6858fc6d9ede' \
--header 'Authorization: Bearer <token>'

Response

{
  "awx_rate": 0.7815,
  "buy_amount": 10000,
  "buy_currency": "USD",
  "client_rate": 0.7816,
  "conversion_date": "2017-03-22",
  "conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
  "created_at": "2017-03-20T10:08:12+1100",
  "currency_pair": "AUDUSD",
  "dealt_currency": "USD",
  "last_updated_at": "2017-03-20T14:00:01+1100",
  "quote_id": "string",
  "reason": "Settling a payment in USD",
  "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
  "sell_amount": 12794.27,
  "sell_currency": "AUD",
  "settlement_cutoff_time": "2017-03-22T14:00:00+1100",
  "short_reference_id": "20170608-AF3GJ9",
  "status": "AWAITING_FUNDS"
}