Third Party FX
Overview
Powering up your platform with Caxton Fx API, enables you to see the rates of exchange for multiple currencies, create quotes, execute them, and ultimately spend money in whichever currency you choose. Whether it’s a retail purchase, or a business payment, a choice of currencies provides you with a wider global reach.
Currencies
There are 6 Main currencies that can be paired with 29 Exchange currencies. These are included in the following tables:
Main Currencies
There are 6 source currencies available. To list them, call the GET - Retrieve Main currencies for Third Parties
endpoint. These include:
Currency | Name |
---|---|
AUD | Australian Dollar |
GBP | British Pound Sterling |
CAD | Canadian Dollar |
EUR | Euro |
NZD | New Zealand Dollar |
USD | US Dollar |
Exchange Currencies
There are 29 currencies available to purchase. To list them, call the GET - Retrieve Exchange currencies for Third Parties.
endpoint. These include:
Currency | Code | Name |
---|---|---|
AUD | 36 | Australian Dollar |
GBP | 826 | British Pound Sterling |
BGN | 975 | Bulgarian Lev |
CAD | 124 | Canadian Dollar |
CZK | 203 | Czech Koruna |
DKK | 208 | Danish Krone |
EUR | 978 | Euro |
HKD | 344 | Hong Kong Dollar |
HUF | 348 | Hungarian Forint |
INR | 356 | Indian Rupee |
ILS | 376 | Israeli New Shekel |
JPY | 392 | Japanese Yen |
KES | 404 | Kenyan Shilling |
KWD | 414 | Kuwaiti Dinar |
MAD | 504 | Moroccan Dirham |
NZD | 554 | New Zealand Dollar |
NOK | 578 | Norwegian Krone |
PLN | 985 | Polish Zloty |
QAR | 634 | Qatari Riyal |
OMR | 512 | Rial Omani |
SAR | 682 | Saudi Riyal |
SGD | 702 | Singapore Dollar |
ZAR | 710 | South African Rand |
SEK | 752 | Swedish Krona |
CHF | 756 | Swiss Franc |
THB | 764 | Thai Baht |
TRY | 949 | Turkish Lira |
AED | 784 | UAE Dirham |
USD | 840 | US Dollar |
NOTE
Attempting to create a Quote based on a currency not listed as a Main or Exchange currency returns an error. Use the currency tables above to validate your request.
Rates
Rates enable you to display the exchange rate for the currencies you wish to convert.
In the following excerpts, we discuss the options available in a bit more detail and provide examples for these concepts.
Trade Main Currency into Exchange Currency
Using this method, the input amount is the Maincurrency, and the output is the Exchange currency. In the request example below, the input is 10GBP and the output becomes 10.80CHF.* To get a rate using this method:
- Call
POST - Display Rates from Main currency to Exchange currency.
- Enter the
CcyCode
. The Exchange currency. - Enter the
SellCcyCode
. The Main currency. - Enter the
Amount
. The amount in the Main currency.
REQUEST
curl --location 'https://caxapi-integration.azurewebsites.net/api/rates/third-party/buy' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"QuoteChannelType": 33,
"CcyCode":"CHF",
"SellccyCode":"GBP",
"Amount": 10
}'
RESPONSE
{
"Content": {
"Model": {
"IsEnhancedRate": false,
"BuyAmount": 10.80,
"BuyCurrency": "CHF",
"BuyDesc": "Swiss Franc",
"BuySymbol": "CHF",
"SellAmount": 10.0,
"SellCurrency": "GBP",
"SellDesc": "British Pound Sterling",
"SellSymbol": "£",
"ExchangeRate": 1.0801,
"ChannelType": 33,
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"ExpectedResponses": [
"IsValid"
]
},
"AuthorisedClientModel": {
"ClientId": "<clientid>",
"ClientRef": "<clientref>",
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"AuthorisedUserModel": {
"UserId": "<userid>",
"AppVersion": "20231117.1",
"TokenStartDate": "2023-11-21T00:00:00",
"TokenEndDate": "2023-12-21T00:00:00",
"LoginTimestamp": "2023-12-01T20:43:29.7267638",
"ApiLoginType": 1,
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
}
}
Trade Exchange Currency into Main Currency
Conversely, to find out how much an Exchangecurrency costs in the Main currency, you can use this alternative method. In the request example below, the input is 10CHF and the output becomes 9.26GBP.* To get a rate using this method:
- Call
POST - Display Rates from Exchange currency to Main currency.
. - Enter the
CcyCode
. The Exchange currency. - Enter the
SellCcyCode
. The Main currency used to pay for the request. - Enter the
Amount
. The amount in the Exchange currency.
REQUEST
curl --location 'https://caxapi-integration.azurewebsites.net/api/rates/third-party/sell' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{
"QuoteChannelType": 33,
"CcyCode":"CHF",
"SellccyCode":"GBP",
"Amount": 10
}'
RESPONSE
{
"Content": {
"Model": {
"IsEnhancedRate": false,
"BuyAmount": 10.0,
"BuyCurrency": "CHF",
"BuyDesc": "Swiss Franc",
"BuySymbol": "CHF",
"SellAmount": 9.26,
"SellCurrency": "GBP",
"SellDesc": "British Pound Sterling",
"SellSymbol": "£",
"ExchangeRate": 1.0801,
"ChannelType": 33,
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"ExpectedResponses": [
"IsValid"
]
},
"AuthorisedClientModel": {
"ClientId": "<clientid>",
"ClientRef": "<clientref>",
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"AuthorisedUserModel": {
"UserId": "<userid>",
"AppVersion": "20231117.1",
"TokenStartDate": "2023-11-21T00:00:00",
"TokenEndDate": "2023-12-21T00:00:00",
"LoginTimestamp": "2023-12-01T20:43:29.7267638",
"ApiLoginType": 1,
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
}
}
Quotes
Trade Main Currency into Exchange Currency
In the example below we create a quote using 10GBP as the Main currency amount to make payment, and CHF as the Exchange currency to receive. To create a quote using this method:
- Call the
POST - Create a Quote from a Main currency into an Exchange currency.
endpoint. - Enter the
SellCcycode
. The Main currency being used to pay for the exchange. - Enter the
CcyCode
. The Exchange currency to acquire. - Enter the
Amount
. The amount in the Main currency. - A successful response returns a
QuoteId
.
REQUEST
curl --location 'https://caxapi-integration.azurewebsites.net/api//quotes/third-party/buy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--header 'UserApiToken: <userapitoken>' \
--data '{
"QuoteChannelType": "33",
"SellCcyCode": "GBP",
"CcyCode": "CHF",
"Amount":10,
}'
RESPONSE
{
"Content": {
"Model": {
"QuoteId": 1369708,
"RequestedOn": "2023-12-05T22:52:43.6995136Z",
"ExpiresOn": "2023-12-05T22:57:43.6995136Z",
"IsEnhancedRate": false,
"BuyAmount": 10.78,
"BuyCurrency": "CHF",
"BuyDesc": "Swiss Franc",
"BuySymbol": "CHF",
"SellAmount": 10.0,
"SellCurrency": "GBP",
"SellDesc": "British Pound Sterling",
"SellSymbol": "£",
"ExchangeRate": 1.0781,
"ChannelType": 33,
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"ExpectedResponses": [
"IsValid"
]
},
"AuthorisedClientModel": {
"ClientId": "<clientid>",
"ClientRef": "<clientref>",
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"AuthorisedUserModel": {
"UserId": "<userid>",
"AppVersion": null,
"TokenStartDate": "2023-11-13T00:00:00",
"TokenEndDate": "2023-12-13T00:00:00",
"LoginTimestamp": "2023-12-01T20:45:14.7858085",
"ApiLoginType": 0,
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
}
}
Trade Exchange Currency into Main Currency
In the example request below, we demonstrate how, by entering 10CHF as theExchange currency, the conversion results in 9.28GBP being the Main currency. To create a quote using this method, follow the steps below:
- Call the
POST - Create a Quote from an Exchange currency to a Main currency.
endpoint. - Enter the
SellCcycode
. The Main currency being used to make the trade. - Enter the
CcyCode
. The Exchange currency being requested. - Enter the
Amount
. The amount to purchase in the Exchange currency. This amount in turn, generates the conversion cost amount in the Main currency. i.e how much the conversion costs in the Main currency, - A successful response returns a
QuoteId
.
REQUEST
curl --location 'https://caxapi-integration.azurewebsites.net/api//quotes/third-party/buy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--header 'UserApiToken: <userapitoken>' \
--data '{
"QuoteChannelType": "33",
"SellCcyCode": "GBP",
"CcyCode": "CHF",
"Amount":10,
}'
RESPONSE
{
"Content": {
"Model": {
"QuoteId": 1369707,
"RequestedOn": "2023-12-05T22:31:51.4917177Z",
"ExpiresOn": "2023-12-05T22:36:51.4917177Z",
"IsEnhancedRate": false,
"BuyAmount": 10.0,
"BuyCurrency": "CHF",
"BuyDesc": "Swiss Franc",
"BuySymbol": "CHF",
"SellAmount": 9.28,
"SellCurrency": "GBP",
"SellDesc": "British Pound Sterling",
"SellSymbol": "£",
"ExchangeRate": 1.0780,
"ChannelType": 33,
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"ExpectedResponses": [
"IsValid"
]
},
"AuthorisedClientModel": {
"ClientId": "<clientid>",
"ClientRef": "<clientref>",
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"AuthorisedUserModel": {
"UserId": "<userid>",
"AppVersion": null,
"TokenStartDate": "2023-11-13T00:00:00",
"TokenEndDate": "2023-12-13T00:00:00",
"LoginTimestamp": "2023-12-01T20:45:14.7858085",
"ApiLoginType": 0,
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
}
}
Once the quote is created, the GET - Retrieve a Quote by Id.
endpoint can be called to retrieve information regarding the quote. Quotes are only valid for a total of 5 minutes from when they are first created. If the time has elapsed, the request returns an error.
Execution
Depending on the currency being traded, it can take between 2 - 4 working days to settle the amount.
To execute the quote and complete the trade:
- Call
POST - Executes a Quote
. - A successful response is shown below:
RESPONSE
{
"Content": {
"Model": {
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"ExpectedResponses": [
"IsValid"
]
},
"AuthorisedClientModel": {
"ClientId": "<clientid>",
"ClientRef": "<clientref>",
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
"AuthorisedUserModel": {
"UserId": "<userid>",
"AppVersion": "20231117.1",
"TokenStartDate": "2023-11-21T00:00:00",
"TokenEndDate": "2023-12-21T00:00:00",
"LoginTimestamp": "2023-12-06T11:41:23.3089019",
"ApiLoginType": 1,
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
}
}
As shown in the response below, once the quote is executed successfully, the expected response when GET - Retrieve a Quote by Id.
is called, should reflect this change by switching the ApiStatus
to QuoteIsExecuted
:
RESPONSE
"ExpectedResponses": [
"IsValid"
],
"ApiStatusCode": 509,
"ApiStatus": "QuoteIsExecuted",
"ApiStatusDescription": "The requested quote has already been executed"
}
For further verification, the Main Balance on the account should reflect any deductions and/or credits, you can check this by calling the GET - Retrieve Main Currency Balances
endpoint.
Settlement
When creating a quote, it can be useful to know exactly when the funds become available. For this purpose:
- Call the
POST Quotes Settlement
endpoint. - Enter the
QuoteId
in the path parameters. - A successful response displays the information for that particular quote, along with the
Days
andSettlementDate
properties to highlight how many days, as well as, the exact date and time when the funds become available.
A successful response is shown below, with the Days
remaining showing as 1 and the SettlementDate
showing in YYYY/MM/DD and HH/MM/SS:
RESPONSE
{
"Content": {
"Model": {
"Result": {
"BuyAmount": 400.00,
"BuyCurrency": "EUR",
"SellAmount": 353.75,
"SellCurrency": "GBP",
"Days": 1,
"SettlementDate": "2023-10-04T00:00:00+00:00",
"ApiStatusCode": 100,
"ApiStatus": "IsValid",
"ApiStatusDescription": "Valid Operation"
},
Updated 7 months ago