LockFX 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
}Step 2: Create a new Quote
The quote API 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 API 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 API, 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 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": 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 API 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"
}