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/fx/conversions/create
GET /api/v1/fx/conversions/{conversion_id}
GET /api/v1/fx/conversions

Create a conversion

POST /api/v1/fx/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 with payouts.)

If using Quotes, users must provide a valid Quote ID in the conversion request. The key details of the conversion request such as buy_currency, sell_currency, and conversion_date (if specified) must match the quote details. Otherwise, users can leave the Quote ID field blank, resulting in the conversion being executed at the 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 $1.

Request body

buy_currencyrequiredstring

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

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).

application_fee_optionsarray

The application fee options applied to the transaction.

application_fee_options.amountstring

A positive integer specifying the amount of the fee expressed in the smallest unit of the currency. e.g. cents for USD. This field is required only when type is FIXED.

application_fee_options.currencystring

Specify the currency of the application fee in ISO 4217 currency code format, e.g., USD, AUD. This field is required when the type is FIXED.
When the type is PERCENTAGE and source_type is CONVERSION, the currency for the conversion if specified must be from the currency pair. If the currency is unspecified, the contra currency of the quote will be used.

application_fee_options.metadataobject

The metadata of the application fee. The value should be set in key:value format. (e.g., id:1).

application_fee_options.percentagestring

Required if the type is PERCENTAGE, and the value to be provided depends on the transaction context.
FX Conversions: The value acts as a markup on the FX rate, increasing the conversion cost by the specified percentage.
Others: The value represents a direct fee calculated as a percentage of the transaction amount.

application_fee_options.source_typestring

Specify type of the source transaction.

CONVERSION, TRANSFER

application_fee_options.typestring

Define the type of fee calculation. If the source_type is CONVERSION, then the type must be PERCENTAGE.

FIXED, PERCENTAGE

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.

funding_sourceobject

The funding information for this conversion. By default (when the funding object is not specified), conversions will source funds from the wallet.

funding_source.idrequiredstring

The funding source unique identifier only supports Linked Accounts. Please provide the unique identifier of your Linked Account as returned in Create a Linked Account. Note that if not specified, the funding source will default to your Wallet.

funding_source.debit_typestring

The type of deposit you would like to create, either DIRECT_DEBIT or FASTER_DIRECT_DEBIT. If not specified, it will default to DIRECT_DEBIT

metadataobject

A set of key-value pairs for storing your own data together with the conversion.

quote_idstring

Provide a valid Quote unique identifier if you want the conversion executed at the client_rate returned in the quote.

sell_amountstring

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

Response body - 201 Created

application_fee_optionsarray

The application fee options applied to the transaction.

application_fee_options.amountstring

A positive integer specifying the amount of the fee expressed in the smallest unit of the currency. e.g. cents for USD. This field is required only when type is FIXED.

application_fee_options.currencystring

application_fee_options.metadataobject

The metadata of the application fee. The value should be set in key:value format. (e.g., id:1).

application_fee_options.percentagestring

application_fee_options.source_typestring

Specify type of the source transaction.

CONVERSION, TRANSFER

application_fee_options.typestring

Define the type of fee calculation. If the source_type is CONVERSION, then the type must be PERCENTAGE.

FIXED, PERCENTAGE

application_feesarray

Application fees in this transaction.

application_fees.amountstring

The application fee amount.

application_fees.currencystring

The currency of the application fee.

application_fees.source_typestring

Specify the type of source transaction for this application fee.

CONVERSION, TRANSFER

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).

fundingobject

The funding information for this conversion.

funding.debit_typestring

Can be one of: FASTER_DIRECT_DEBIT, DIRECT_DEBIT.

funding.failure_reasonstring

Empty unless the funding is in an error state.

funding.funding_source_idstring

The id of the funding source, it can be null if using a wallet.

funding.statusstring

The funding statuses of this conversion.

funding_sourceobject

The funding information for this conversion.

funding_source.idstring

funding_source.debit_typestring

The type of deposit you would like to create, either DIRECT_DEBIT or FASTER_DIRECT_DEBIT. If not specified, it will default to DIRECT_DEBIT

mid_ratenumber

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

quote_idstring

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

rate_detailsarray

Breakdown of rates at different user levels.

rate_details.buy_amountnumber

The total amount being bought at the respective level.

rate_details.levelstring

Supported levels include: CLIENT, AWX, PLATFORM_CLIENT

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.

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_atstring

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 SCHEDULED, CANCELLED, OVERDUE, SETTLED.

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.

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`, `unsupported_currency`
401	Possible errors: `credentials_invalid`, `credentials_expired`
429	Too many requests
500	Service unavailable

POST /api/v1/fx/conversions/create

$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/fx/conversions/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "application_fee_options": [
>    {
>      "amount": "5",
>      "currency": "AUD",
>      "percentage": "0.1",
>      "source_type": "TRANSFER",
>      "type": "FIXED"
>    }
>  ],
>  "buy_amount": "10000",
>  "buy_currency": "USD",
>  "conversion_date": "2017-03-22",
>  "funding_source": {
>    "debit_type": "DIRECT_DEBIT",
>    "id": "<string>"
>  },
>  "metadata": {},
>  "quote_id": "<string>",
>  "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
>  "sell_amount": "<string>",
>  "sell_currency": "AUD"
>}'

Response (201 Created)

1{
2  "application_fee_options": [
3    {
4      "amount": "5",
5      "currency": "AUD",
6      "percentage": "0.1",
7      "source_type": "TRANSFER",
8      "type": "FIXED"
9    }
10  ],
11  "application_fees": [
12    {
13      "amount": "5",
14      "currency": "AUD",
15      "source_type": "TRANSFER"
16    }
17  ],
18  "awx_rate": 0.781523,
19  "buy_amount": "10000",
20  "buy_currency": "USD",
21  "client_rate": 0.781623,
22  "conversion_date": "2017-03-22",
23  "conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
24  "created_at": "2017-03-20T10:08:12+1100",
25  "currency_pair": "AUDUSD",
26  "dealt_currency": "USD",
27  "funding": {
28    "debit_type": "DIRECT_DEBIT",
29    "failure_reason": "<string>",
30    "funding_source_id": "<string>",
31    "status": "<string>"
32  },
33  "funding_source": {
34    "debit_type": "DIRECT_DEBIT",
35    "id": "<string>"
36  },
37  "mid_rate": 0.761223,
38  "quote_id": "<string>",
39  "rate_details": [
40    {
41      "buy_amount": "10000",
42      "level": "CLIENT",
43      "rate": 0.781523,
44      "sell_amount": 12794.27
45    }
46  ],
47  "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
48  "sell_amount": 12794.27,
49  "sell_currency": "AUD",
50  "settlement_cutoff_at": "2017-03-22T14:00:00+1100",
51  "short_reference_id": "20170608-AF3GJ9",
52  "status": "SETTLED",
53  "updated_at": "2017-03-20T14:00:01+1100"
54}

Was this section helpful?

Retrieve a conversion

GET /api/v1/fx/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

application_fee_optionsarray

The application fee options applied to the transaction.

application_fee_options.amountstring

A positive integer specifying the amount of the fee expressed in the smallest unit of the currency. e.g. cents for USD. This field is required only when type is FIXED.

application_fee_options.currencystring

application_fee_options.metadataobject

The metadata of the application fee. The value should be set in key:value format. (e.g., id:1).

application_fee_options.percentagestring

application_fee_options.source_typestring

Specify type of the source transaction.

CONVERSION, TRANSFER

application_fee_options.typestring

Define the type of fee calculation. If the source_type is CONVERSION, then the type must be PERCENTAGE.

FIXED, PERCENTAGE

application_feesarray

Application fees in this transaction.

application_fees.amountstring

The application fee amount.

application_fees.currencystring

The currency of the application fee.

application_fees.source_typestring

Specify the type of source transaction for this application fee.

CONVERSION, TRANSFER

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).

fundingobject

The funding information for this conversion.

funding.debit_typestring

Can be one of: FASTER_DIRECT_DEBIT, DIRECT_DEBIT.

funding.failure_reasonstring

Empty unless the funding is in an error state.

funding.funding_source_idstring

The id of the funding source, it can be null if using a wallet.

funding.statusstring

The funding statuses of this conversion.

funding_sourceobject

The funding information for this conversion.

funding_source.idstring

funding_source.debit_typestring

The type of deposit you would like to create, either DIRECT_DEBIT or FASTER_DIRECT_DEBIT. If not specified, it will default to DIRECT_DEBIT

mid_ratenumber

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

quote_idstring

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

rate_detailsarray

Breakdown of rates at different user levels.

rate_details.buy_amountnumber

The total amount being bought at the respective level.

rate_details.levelstring

Supported levels include: CLIENT, AWX, PLATFORM_CLIENT

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.

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_atstring

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 SCHEDULED, CANCELLED, OVERDUE, SETTLED.

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.

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/fx/conversions/{conversion_id}

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

Response (200 OK)

1{
2  "application_fee_options": [
3    {
4      "amount": "5",
5      "currency": "AUD",
6      "percentage": "0.1",
7      "source_type": "TRANSFER",
8      "type": "FIXED"
9    }
10  ],
11  "application_fees": [
12    {
13      "amount": "5",
14      "currency": "AUD",
15      "source_type": "TRANSFER"
16    }
17  ],
18  "awx_rate": 0.781523,
19  "buy_amount": 10000,
20  "buy_currency": "USD",
21  "client_rate": 0.781623,
22  "conversion_date": "2017-03-22",
23  "conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
24  "created_at": "2017-03-20T10:08:12+1100",
25  "currency_pair": "AUDUSD",
26  "dealt_currency": "USD",
27  "funding": {
28    "debit_type": "DIRECT_DEBIT",
29    "failure_reason": "<string>",
30    "funding_source_id": "<string>",
31    "status": "<string>"
32  },
33  "funding_source": {
34    "debit_type": "DIRECT_DEBIT",
35    "id": "<string>"
36  },
37  "mid_rate": 0.761223,
38  "quote_id": "<string>",
39  "rate_details": [
40    {
41      "buy_amount": 10000,
42      "level": "CLIENT",
43      "rate": 0.781523,
44      "sell_amount": 12794.27
45    }
46  ],
47  "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
48  "sell_amount": 12794.27,
49  "sell_currency": "AUD",
50  "settlement_cutoff_at": "2017-03-22T14:00:00+1100",
51  "short_reference_id": "20170608-AF3GJ9",
52  "status": "SETTLED",
53  "updated_at": "2017-03-20T14:00:01+1100"
54}

Was this section helpful?

List all conversions

GET /api/v1/fx/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 ofSCHEDULED, OVERDUE, CANCELLED, SETTLED.

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.mid_ratenumber

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

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_atstring

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 SCHEDULED, CANCELLED, OVERDUE, SETTLED.

items.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.application_fee_optionsarray

The application fee options applied to the transaction.

items.application_fee_options.amountstring

A positive integer specifying the amount of the fee expressed in the smallest unit of the currency. e.g. cents for USD. This field is required only when type is FIXED.

items.application_fee_options.currencystring

items.application_fee_options.metadataobject

The metadata of the application fee. The value should be set in key:value format. (e.g., id:1).

items.application_fee_options.percentagestring

items.application_fee_options.source_typestring

Specify type of the source transaction.

CONVERSION, TRANSFER

items.application_fee_options.typestring

Define the type of fee calculation. If the source_type is CONVERSION, then the type must be PERCENTAGE.

FIXED, PERCENTAGE

items.application_feesarray

Application fees in this transaction.

items.application_fees.amountstring

The application fee amount.

items.application_fees.currencystring

The currency of the application fee.

items.application_fees.source_typestring

Specify the type of source transaction for this application fee.

CONVERSION, TRANSFER

items.fundingobject

The funding information for this conversion.

items.funding.debit_typestring

Can be one of: FASTER_DIRECT_DEBIT, DIRECT_DEBIT.

items.funding.failure_reasonstring

Empty unless the funding is in an error state.

items.funding.funding_source_idstring

The id of the funding source, it can be null if using a wallet.

items.funding.statusstring

The funding statuses of this conversion.

items.funding_sourceobject

The funding information for this conversion.

items.funding_source.idstring

items.funding_source.debit_typestring

The type of deposit you would like to create, either DIRECT_DEBIT or FASTER_DIRECT_DEBIT. If not specified, it will default to DIRECT_DEBIT

items.quote_idstring

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

items.rate_detailsarray

Breakdown of rates at different user levels.

items.rate_details.buy_amountnumber

The total amount being bought at the respective level.

items.rate_details.levelstring

Supported levels include: CLIENT, AWX, PLATFORM_CLIENT

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/fx/conversions

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

Response (200 OK)

1{
2  "has_more": false,
3  "items": [
4    {
5      "application_fee_options": [
6        {
7          "amount": "5",
8          "currency": "AUD",
9          "percentage": "0.1",
10          "source_type": "TRANSFER",
11          "type": "FIXED"
12        }
13      ],
14      "application_fees": [
15        {
16          "amount": "5",
17          "currency": "AUD",
18          "source_type": "TRANSFER"
19        }
20      ],
21      "awx_rate": 0.781523,
22      "buy_amount": 10000,
23      "buy_currency": "USD",
24      "client_rate": 0.781623,
25      "conversion_date": "2017-03-22",
26      "conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",
27      "created_at": "2017-03-20T10:08:12+1100",
28      "currency_pair": "AUDUSD",
29      "dealt_currency": "USD",
30      "mid_rate": 0.761223,
31      "rate_details": [
32        {
33          "buy_amount": 10000,
34          "level": "CLIENT",
35          "rate": 0.781523,
36          "sell_amount": 12794.27
37        }
38      ],
39      "request_id": "67f687fe-dcf4-4462-92fa-20335301d9d8",
40      "sell_amount": 12794.27,
41      "sell_currency": "AUD",
42      "settlement_cutoff_at": "2017-03-22T14:00:00+1100",
43      "short_reference_id": "20170608-AF3GJ9",
44      "status": "SETTLED",
45      "updated_at": "2017-03-20T14:00:01+1100"
46    }
47  ]
48}

Was this section helpful?