Guides

Wallet FX

Suggest Edits

Overview

Wallets enable users to store Cards and Currencies. In this section, we discuss some of the available options to retrieve exchange rates and execute Card quotes.

Currencies

Cards have GBP as their sole Main currency. Once funds are added, there are 15 Exchange currencies available to retrieve FX rates and quotes.

Exchange currencies

There are 15 target currencies available to Card holders. To list them, call the GET - Retrieve Exchange currencies for Cardsendpoint. These include:

CurrencyName
AUDAustralian Dollar
CADCanadian Dollar
CHFSwiss Franc
DKKDanish Krone
EUREuro
GBPBritish Pound Sterling
HKDHong Kong Dollar
HUFHungarian Forint
JPYJapanese Yen
NOKNorwegian Krone
NZDNew Zealand Dollar
PLNPolish Zloty
SEKSwedish Krona
USDUS Dollar
ZARSouth African Rand

Rates

Trade Main Currency into Exchange Currency

To get a rate using this method, the input is the Main currency amount, and the output is the Exchange currency amount. E.g. 100GBP is equal to 107.31CHF.*

  1. Call POST - Display Rates from Main currency to Exchange currency..
  2. Enter the CcyCode. The Exchange currency to acquire.
  3. Enter the sellccycode. The Main currency being used to pay for the exchange.
  4. Enter the Amount. The amount in the Main currency.

REQUEST

curl --location 'https://caxapi-integration.azurewebsites.net/api/rates/card/buy' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{    
	"CcyCode":"CHF",
	"SellccyCode":"GBP",
	"Amount": 100,
}'

RESPONSE

{
    "Content": {
        "Model": {
            "IsEnhancedRate": false,
            "BuyAmount": 107.31,
            "BuyCurrency": "CHF",
            "BuyDesc": "Swiss Franc",
            "BuySymbol": "CHF",
            "SellAmount": 100.0,
            "SellCurrency": "GBP",
            "SellDesc": "British Pound Sterling",
            "SellSymbol": "£",
            "ExchangeRate": 1.0731,
            "ChannelType": 18,
            "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"
    }
}

Trade Exchange Currency into Main Currency

In the example request below, we demonstrate how, by entering 107.31CHF as our Exchange currency, the conversion rate means we pay a total of ~100GBP in our Main currency. To get a rate using this method, follow the steps below:

  1. Call POST - Display Rates from Exchange currency to Main currency. to get a Card rate using this method.
  2. Enter the CcyCode. This is the three-letter code of the Exchange currency.
  3. Enter the SellccyCode. This is the three-letter code for the Main currency.
  4. Enter the amount. This is the amount of the currency to quote.
  5. A successful response returns the cost of the exchange in the Main currency. In this case GBP.

REQUEST

curl --location 'https://caxapi-integration.azurewebsites.net/api/rates/card/buy' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \
--data '{    
	"CcyCode":"CHF",
	"SellccyCode":"GBP",
	"Amount": 107.31,
  
}'

RESPONSE

{
    "Content": {
        "Model": {
            "IsEnhancedRate": false,
            "BuyAmount": 107.31,
            "BuyCurrency": "CHF",
            "BuyDesc": "Swiss Franc",
            "BuySymbol": "CHF",
            "SellAmount": 100.02,
            "SellCurrency": "GBP",
            "SellDesc": "British Pound Sterling",
            "SellSymbol": "£",
            "ExchangeRate": 1.0729,
            "ChannelType": 18,
            "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"
    }
}

Quotes

Trade Main Currency into Exchange Currency

When you wish to create a quote using this method, the input amount is the Exchange currency you wish to purchase, and the output is the amount to pay in your Main currency. E.g. To buy 10 EUR the cost is 8.87 GBP.*

Cards

  1. Call POST - Create a Card Quote from an Exchange currency into a Main currency..
  2. Enter the CcyCode. The currency you wish to get a quote for.
  3. Enter the amount. The amount in the currency you wish to purchase.
  4. A successful response returns a QuoteId. This unique code is valid for up to five minutes from the moment the Quote is requested, and must be executed within that time period to complete the trade.

REQUEST

curl --location 'https://caxapi-integration.azurewebsites.net/api//quotes/retail/card/buy' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--data '{	
	"CcyCode":"EUR",	
	"Amount": 10	
}'

RESPONSE

{
    "Content": {
        "Model": {
            "QuoteId": 1369644,
            "RequestedOn": "2023-12-04T13:10:24.5477815Z",
            "ExpiresOn": "2023-12-04T13:15:24.5477815Z",
            "IsEnhancedRate": false,
            "BuyAmount": 10.0,
            "BuyCurrency": "EUR",
            "BuyDesc": "Euro",
            "BuySymbol": "€",
            "SellAmount": 8.87,
            "SellCurrency": "GBP",
            "SellDesc": "British Pound Sterling",
            "SellSymbol": "£",
            "ExchangeRate": 1.1277,
            "ChannelType": 18,
            "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

Conversely, to create a quote to find out how much you have to spend in your Main currency to get a particular Exchange currency, you can use this alternative method. E.g. Spend 8.87 GBP and receive 10 EUR.*

Card quotes are created by:

  1. Call the POST - Create a Quote by Trading a Main currency into an Exchange currency. endpoint.
  2. Enter the CcyCode. The currency you wish to get a quote for.
  3. Enter the amount. By default, this is set to GBP.
  4. A successful response returns a QuoteId. This unique code is valid for up to five minutes from the moment the Quote is requested, and must be executed within that time period to complete the trade.

REQUEST

curl --location 'https://caxapi-integration.azurewebsites.net/api/quotes/retail/card//sell' \
--header 'Authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--header 'Content-Type: application/json' \
--data '{
	"CcyCode":"EUR",
	"Amount":"8.87"
}'

RESPONSE

{
    "Content": {
        "Model": {
            "QuoteId": 1369762,
            "RequestedOn": "2023-12-06T15:56:11.0800032Z",
            "ExpiresOn": "2023-12-06T16:01:11.0800032Z",
            "IsEnhancedRate": false,
            "BuyAmount": 10.01,
            "BuyCurrency": "EUR",
            "BuyDesc": "Euro",
            "BuySymbol": "€",
            "SellAmount": 8.87,
            "SellCurrency": "GBP",
            "SellDesc": "British Pound Sterling",
            "SellSymbol": "£",
            "ExchangeRate": 1.1289,
            "ChannelType": 18,
            "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-06T11:05:59.255352",
        "ApiLoginType": 0,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

Execution

Step 1. Initiate Request with a QuoteId

To fund a Wallet via QuoteId:

  1. Call POST - Initiate a Payment Request via Currency Balance for Card Quotes..
  2. Enter the WalletId.
  3. Enter the QuoteId.
  4. A successful response returns a ShopOrderId which is used to process the request.

The following is an example request:

REQUEST

curl --location 'https://caxapi-integration.azurewebsites.net/api/payments/currency-bank/card-load' \
--header 'Authorization: Bearer <access_token>' \
--header 'userapitoken: <userapitoken>' \
--header 'Content-Type: application/json' \
--data '{
    "WalletId":123456,
    "QuoteId":{{quoteid}}
   /// "Currency" : "GBP",
   /// "Amount" : "12345"
}'

📘

Note

Quotes are given a five minute allocation to be executed. The load request must be initiated before the time expires or the quote has to be generated again.

RESPONSE

The following response is returned. Note the ShopOrderID created on line 4:

{
    "Content": {
        "Model": {
            "ShopOrderId": "578a7ec6-cf4d-40c4-8f3a-fc270aa6c20f",
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
    }
}

Step 2. Process a Request to Fund a Wallet

After initiating a request successfully, a ShopOrderId is used to process the request. To do so follow the instructions below:

  1. Call the POST - Process Currency Balance Payload.
  2. Enter the ShopOrderId generated in previous steps.
  3. A successful response returns a PaymentProcessId.

REQUEST

{
    "ShopOrderId":"578a7ec6-cf4d-40c4-8f3a-fc270aa6c20f"
}

RESPONSE

A successful response is shown below. Note the PaymentProcessId created on line 5:

{
    "Content": {
        "Model": {
            "PaymentProcessId": "578a7ec6-cf4d-40c4-8f3a-fc270aa6c20f",
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
        },

Settlement

When creating a quote, it can be useful to know exactly when the funds become available. For this purpose:

  1. Call the POST - Quotes Settlement endpoint.
  2. Enter the QuoteId in the path parameters.
  3. A successful response displays the information for that particular quote, along with the Days and SettlementDate properties to highlight how many days, as well as, the exact date and time before 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 9 months ago