Airwallex logo

LockFX Quickstart

Step 1: Check Balance

Checking the Airwallex Wallet Balance 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
  }

Step 2: Create a 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 Request

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 3: Store the 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 conversion 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 4: Create a new 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 Request

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 4a: Create a new Payment

Alternatively, by specifying different payment_currency and source_currency parameters when requesting a payment , you will trigger an underlying currency conversion. You will need to ensure: a valid quote_id is passed in the request; the client_sell_currency from the quote response matches the source_currency in the payment request; and the client_buy_currency from the quote response matches the payment_currency in the payment request

Sample Request

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

Step 5: Check Balance

Following a successful conversion, the Airwallex Wallet Balance 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": 9991.38,
    "currency": "USD",
    "pending_amount": 5000,
    "reserved_amount": 0,
    "total_amount": 14991.38
  },
 {
    "available_amount": 67.75,
    "currency": "HKD",
    "pending_amount": 0,
    "reserved_amount": 0,
    "total_amount": 67.75
  }

Step 6: Retrieve the previously created Transaction Status

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