Conversion

The Conversion resources provide capability to create transactions that convert from one currency into another. The transaction will result in a debit and credit against your wallet balances. Both Quotes and Rates transactions can be created using the Conversion resources.

Endpoints

POST /api/v1/conversions/create
GET /api/v1/conversions/{conversion_id}
GET /api/v1/conversions

Create a conversion

POST /api/v1/conversions/create

Copy for LLMView as Markdown

Create a new conversion to be executed within your Airwallex wallet. To associate a conversion with a payout, use the Payment API. (Note: Some exotic currencies require conversions to be associated to payouts.)

LockFX users must populate a valid LockFX Quote ID on the conversion request. Note that the quote must be unexpired, and that key details of the conversion request (such as buy_currency, sell_currency, and conversion_date) must match quote details.

MarketFX users do not need to populate a Quote ID; leaving this field blank will result in the conversion executing at current market rate.

On a conversion, populate both buy_currency and sell_currency, but define only one of either buy_amount or sell_amount. This populated amount defines the dealt (also known as fixed) side of the conversion. The other amount will be computed by Airwallex based on the exchange rate of the conversion. The minimum conversion limit per conversion is USD $10.

Request body

buy_currencyrequiredstring

Currency that the client buys (in 3-letter ISO-4217 format).

reasonrequiredstring

Provide a reason for FX conversion request. Parameter supports a maximum of 512 characters.

request_idrequiredstring

Client-generated idempotency key. Must be unique per request attempt. Conversion requests with the same request_id will be rejected. Parameter supports a maximum of 64 characters.

sell_currencyrequiredstring

Currency that the client sells (in 3-letter ISO-4217 format).

term_agreementrequiredboolean

Confirm client’s agreement to Airwallex’s Terms and Conditions .

buy_amountstring

Amount in buy_currency that the client buys. Must be specified if sell_amount is not specified.

conversion_datestring

Date on which the conversion will be settled. conversion_date defaults to current date, if funding is available, unless specified.

quote_idstring

LockFX users must supply a valid LockFX Quote unique identifier.

sell_amountstring

Amount in sell_currency that the client sells. Must be specified if buy_amount is not specified.

Response body - 201 Created

awx_ratenumber

For reference purposes only. This is a reference rate Airwallex compiles by analyzing prices across multiple banking providers and independent rate publishers.

buy_amountnumber

The amount in buy_currency that was bought by the client.

buy_currencystring

Currency that the client bought (in 3-letter ISO-4217 format).

client_ratenumber

The transaction execution rate of the conversion. This is the rate at which the client is charged.

conversion_datestring

Date on which the conversion will be settled. conversion_date defaults to current date, if funding is available, unless specified.

conversion_idstring

Airwallex-generated unique identifier for the conversion record.

created_atstring

The time at which the conversion was created. Follows the same timestamp format as the rest of Airwallex’s APIs.

currency_pairstring

The currency pair associated with awx_rate and client_rate.

dealt_currencystring

Dealt denotes the fixed side of the conversion request. If buy_amount was specified, then buy_currency; else, sell_currency (in 3-letter ISO-4217 format).

last_updated_atstring

The time at which the conversion was last updated (including status changes). Follows the same timestamp format as the rest of Airwallex’s APIs.

mid_ratenumber

For reference purposes only. This rate represents the midpoint of the current bid and ask price.

quote_idstring

The LockFX Quote used to execute the conversion. Echoes the request’s LockFX Quote, if provided.

rate_detailsarray

Breakdown of rates at different user levels. Currently only CLIENT levels are supported.

rate_details.buy_amountnumber

The total amount being bought at the respective level.

rate_details.levelstring

Level of the view. CLIENT and AWX level supported

CLIENT, AWX

rate_details.ratenumber

The exchange rate from the respective level's perspective.

rate_details.sell_amountnumber

The total amount being sold at the respective level.

reasonstring

Echoes request’s client-supplied reason for conversion.

request_idstring

Echoes request’s client-supplied request unique identifier (idempotency key).

sell_amountnumber

The amount in sell_currency that was sold by the client.

sell_currencystring

Currency that the client sold (in 3-letter ISO-4217 format).

settlement_cutoff_timestring

This is latest time by which the sell_amount in sell_currency needs to be available in Airwallex account balance for the conversion to be successfully settled.

short_reference_idstring

Shortened transaction unique identifier for ease of use within Web GUI and with Airwallex support.

statusstring

Status of the conversion. Can be one of AWAITING_FUNDS, CANCELLED, PENDING_SETTLEMENT, SETTLED.

Deprecated: ROLLOVER_REQUESTED, PENDING_ROLLOVER

Errors

Error status	Description
400	Possible errors: `amount_above_limit`, `amount_below_limit`, `conflict_original_ccy`, `expired_quote`, `field_required`, `invalid_argument`, `invalid_endpoint`, `invalid_quote_id`, `invalid_settlement_date`, `operation_failed`, `term_agreement_is_required`, `unsupported_currency`
401	Possible errors: `credentials_invalid`, `credentials_expired`
429	Too many requests
500	Service unavailable

POST /api/v1/conversions/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/conversions/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "buy_amount": "10000",
>  "buy_currency": "USD",
>  "conversion_date": "2017-03-22",
>  "quote_id": "<string>",
>  "reason": "Settling invoices",
>  "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
>  "sell_amount": "<string>",
>  "sell_currency": "AUD",
>  "term_agreement": true
>}'

Response (201 Created)

1{
2  "awx_rate": 0.781523,
3  "buy_amount": "10000",
4  "buy_currency": "USD",
5  "client_rate": 0.781623,
6  "conversion_date": "2017-03-22",
7  "conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
8  "created_at": "2017-03-20T10:08:12+1100",
9  "currency_pair": "AUDUSD",
10  "dealt_currency": "USD",
11  "last_updated_at": "2017-03-20T14:00:01+1100",
12  "mid_rate": 0.761223,
13  "quote_id": "<string>",
14  "rate_details": [
15    {
16      "buy_amount": "10000",
17      "level": "CLIENT",
18      "rate": 0.781523,
19      "sell_amount": 12794.27
20    }
21  ],
22  "reason": "Settling a payment in USD",
23  "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
24  "sell_amount": 12794.27,
25  "sell_currency": "AUD",
26  "settlement_cutoff_time": "2017-03-22T14:00:00+1100",
27  "short_reference_id": "20170608-AF3GJ9",
28  "status": "AWAITING_FUNDS"
29}

Was this section helpful?

Retrieve a conversion

GET /api/v1/conversions/{conversion_id}

Copy for LLMView as Markdown

Get a specific conversion by specifying the Airwallex conversion_id.

Parameters

conversion_idrequiredstring

Unique identifier of the conversion to retrieve.

Response body - 200 OK

awx_ratenumber

For reference purposes only. This is a reference rate Airwallex compiles by analyzing prices across multiple banking providers and independent rate publishers.

buy_amountnumber

The amount in buy_currency that was bought by the client.

buy_currencystring

Currency that the client bought (in 3-letter ISO-4217 format).

client_ratenumber

The transaction execution rate of the conversion. This is the rate at which the client is charged.

conversion_datestring

Date on which the conversion will be settled. conversion_date defaults to current date, if funding is available, unless specified.

conversion_idstring

Airwallex-generated unique identifier for the conversion record.

created_atstring

The time at which the conversion was created. Follows the same timestamp format as the rest of Airwallex’s APIs.

currency_pairstring

The currency pair associated with awx_rate and client_rate.

dealt_currencystring

Dealt denotes the fixed side of the conversion request. If buy_amount was specified, then buy_currency; else, sell_currency (in 3-letter ISO-4217 format).

last_updated_atstring

The time at which the conversion was last updated (including status changes). Follows the same timestamp format as the rest of Airwallex’s APIs.

mid_ratenumber

For reference purposes only. This rate represents the midpoint of the current bid and ask price.

quote_idstring

The LockFX Quote used to execute the conversion. Echoes the request’s LockFX Quote, if provided.

rate_detailsarray

Breakdown of rates at different user levels. Currently only CLIENT levels are supported.

rate_details.buy_amountnumber

The total amount being bought at the respective level.

rate_details.levelstring

Level of the view. CLIENT and AWX level supported

CLIENT, AWX

rate_details.ratenumber

The exchange rate from the respective level's perspective.

rate_details.sell_amountnumber

The total amount being sold at the respective level.

reasonstring

Echoes request’s client-supplied reason for conversion.

request_idstring

Echoes request’s client-supplied request unique identifier (idempotency key).

sell_amountnumber

The amount in sell_currency that was sold by the client.

sell_currencystring

Currency that the client sold (in 3-letter ISO-4217 format).

settlement_cutoff_timestring

This is latest time by which the sell_amount in sell_currency needs to be available in Airwallex account balance for the conversion to be successfully settled.

short_reference_idstring

Shortened transaction unique identifier for ease of use within Web GUI and with Airwallex support.

statusstring

Status of the conversion. Can be one of AWAITING_FUNDS, CANCELLED, PENDING_SETTLEMENT, SETTLED.

Deprecated: ROLLOVER_REQUESTED, PENDING_ROLLOVER

Errors

Error status	Description
400	["field_required" ,"invalid_argument" ,]
401	Possible errors: `credentials_invalid`, `credentials_expired`
404	Possible errors: `not_found`
429	Too many requests
500	Service unavailable

GET /api/v1/conversions/{conversion_id}

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/conversions/conversion_id' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "awx_rate": 0.781523,
3  "buy_amount": 10000,
4  "buy_currency": "USD",
5  "client_rate": 0.781623,
6  "conversion_date": "2017-03-22",
7  "conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
8  "created_at": "2017-03-20T10:08:12+1100",
9  "currency_pair": "AUDUSD",
10  "dealt_currency": "USD",
11  "last_updated_at": "2017-03-20T14:00:01+1100",
12  "mid_rate": 0.761223,
13  "quote_id": "<string>",
14  "rate_details": [
15    {
16      "buy_amount": 10000,
17      "level": "CLIENT",
18      "rate": 0.781523,
19      "sell_amount": 12794.27
20    }
21  ],
22  "reason": "Settling a payment in USD",
23  "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
24  "sell_amount": 12794.27,
25  "sell_currency": "AUD",
26  "settlement_cutoff_time": "2017-03-22T14:00:00+1100",
27  "short_reference_id": "20170608-AF3GJ9",
28  "status": "AWAITING_FUNDS"
29}

Was this section helpful?

List all conversions

GET /api/v1/conversions

Copy for LLMView as Markdown

Retrieve conversions, using any combination of optional queryable parameters below. You may specify none, one of, or both from_created_at or to_created_at parameters. If none of these parameters are specified, results for the last 31 days will be returned. If only one of these parameters are specified, we will assume a 31-day range to calculate the other, undefined parameter. The conversions are returned in descending order, with the most recent transactions appearing first. Each queryable parameter below supports only one defined value at a time.

Parameters

buy_currencystring

Currency that the client bought (in 3-letter ISO-4217 format).

from_created_atstring

The starting value for specifying a date range for results to be returned. The date range is specific to conversion creation (a conversion's created_at date). Specify a starting created_at date (in ISO-8601 format). This starting date is inclusive of the range.

page_numinteger

Page number, starts from 0.

page_sizeinteger

Number of results per page. Default value is 100.

request_idstring

Client-supplied conversion request_id (idempotency key).

sell_currencystring

Currency that the client sold (in 3-letter ISO-4217 format).

statusstring

Status of the conversion. Can be one of AWAITING_FUNDS,CANCELLED,PENDING_SETTLEMENT,SETTLED,ROLLOVER_REQUESTED,PENDING_ROLLOVER.

to_created_atstring

The ending value for specifying a date range for results to be returned. The date range is specific to conversion creation (a conversion's created_at date). Specify an ending created_at date (in ISO-8601 format). This ending date is inclusive of the range.

Response body - 200 OK

has_moreboolean

A flag which identifies whether there are more results.

itemsarray

Paged results.

items.awx_ratenumber

For reference purposes only. This is a reference rate Airwallex compiles by analyzing prices across multiple banking providers and independent rate publishers.

items.buy_amountnumber

The amount in buy_currency that was bought by the client.

items.buy_currencystring

Currency that the client bought (in 3-letter ISO-4217 format).

items.client_ratenumber

The transaction execution rate of the conversion. This is the rate at which the client is charged.

items.conversion_datestring

Date on which the conversion will be settled. conversion_date defaults to current date, if funding is available, unless specified.

items.conversion_idstring

Airwallex-generated unique identifier for the conversion record.

items.created_atstring

The time at which the conversion was created. Follows the same timestamp format as the rest of Airwallex’s APIs.

items.currency_pairstring

The currency pair associated with awx_rate and client_rate.

items.dealt_currencystring

Dealt denotes the fixed side of the conversion request. If buy_amount was specified, then buy_currency; else, sell_currency (in 3-letter ISO-4217 format).

items.last_updated_atstring

The time at which the conversion was last updated (including status changes). Follows the same timestamp format as the rest of Airwallex’s APIs.

items.mid_ratenumber

For reference purposes only. This rate represents the midpoint of the current bid and ask price.

items.reasonstring

Echoes request’s client-supplied reason for conversion.

items.request_idstring

Echoes request’s client-supplied request unique identifier (idempotency key).

items.sell_amountnumber

The amount in sell_currency that was sold by the client.

items.sell_currencystring

Currency that the client sold (in 3-letter ISO-4217 format).

items.settlement_cutoff_timestring

This is latest time by which the sell_amount in sell_currency needs to be available in Airwallex account balance for the conversion to be successfully settled.

items.short_reference_idstring

Shortened transaction unique identifier for ease of use within Web GUI and with Airwallex support.

items.statusstring

Status of the conversion. Can be one of AWAITING_FUNDS, CANCELLED, PENDING_SETTLEMENT, SETTLED.

Deprecated: ROLLOVER_REQUESTED, PENDING_ROLLOVER

items.quote_idstring

The LockFX Quote used to execute the conversion. Echoes the request’s LockFX Quote, if provided.

items.rate_detailsarray

Breakdown of rates at different user levels. Currently only CLIENT levels are supported.

items.rate_details.buy_amountnumber

The total amount being bought at the respective level.

items.rate_details.levelstring

Level of the view. CLIENT and AWX level supported

CLIENT, AWX

items.rate_details.ratenumber

The exchange rate from the respective level's perspective.

items.rate_details.sell_amountnumber

The total amount being sold at the respective level.

Errors

Error status	Description
400	Possible errors: `field_required`, `invalid_argument`
401	Possible errors: `credentials_invalid`, `credentials_expired`
429	Too many requests
500	Service unavailable

GET /api/v1/conversions

$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/conversions' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "awx_rate": 0.781523,
6      "buy_amount": 10000,
7      "buy_currency": "USD",
8      "client_rate": 0.781623,
9      "conversion_date": "2017-03-22",
10      "conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
11      "created_at": "2017-03-20T10:08:12+1100",
12      "currency_pair": "AUDUSD",
13      "dealt_currency": "USD",
14      "last_updated_at": "2017-03-20T14:00:01+1100",
15      "mid_rate": 0.761223,
16      "rate_details": [
17        {
18          "buy_amount": 10000,
19          "level": "CLIENT",
20          "rate": 0.781523,
21          "sell_amount": 12794.27
22        }
23      ],
24      "reason": "Settling a payment in USD",
25      "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
26      "sell_amount": 12794.27,
27      "sell_currency": "AUD",
28      "settlement_cutoff_time": "2017-03-22T14:00:00+1100",
29      "short_reference_id": "20170608-AF3GJ9",
30      "status": "AWAITING_FUNDS"
31    }
32  ]
33}

Was this section helpful?