Fixing FX rates
How to fix FX rates for a period of time
Our system retrieves FX rates on a periodic basis and uses these together with merchant specific margins to generate rates that are then used when transactions are processed by the system. When you post a transaction request to us, we'll typically use the most recent FX rate.
However, if you wish, you can lock in rates for a period of time, and when creating a transaction you can then use these locked rates rather than the prevailing rates. To do this you need to (a) lock in the rates and (b) tell us you want to use those locked rates for a given transaction request.
Locking in rates
To lock in rates for a transaction you create a Rate Group using the API as shown in the following example. When creating this rate group, you need to specify the duration of that group, and also which currencies you are interested in. This will create a set of currency pairs in our system, and report these values to you should you need them.
The API is very simple to call - simply make a POST request as follows...
POST api/forex/2/EUR,AUD,GBP
{
"Currencies": [
{
"Code": "AUD",
"Rates": [
{
"Code": "EUR",
"Value": 0.59933
},
{
"Code": "GBP",
"Value": 0.55081
}
]
},
{
"Code": "EUR",
"Rates": [
{
"Code": "AUD",
"Value": 1.63531
},
{
"Code": "GBP",
"Value": 0.90984
}
]
},
{
"Code": "GBP",
"Rates": [
{
"Code": "AUD",
"Value": 1.77937
},
{
"Code": "EUR",
"Value": 1.07721
}
]
}
],
"ExpiresOn": "2019-08-23T09:33:20.21Z",
"RateGroupId": 375
}The value "2" in the API call above indicates how many days you want to lock the rates in for. In the example above this has locked rates for 2 days. This value has a minimum of 1 and the maximum is defined by your account manager.
You can specify which currencies you are interested in by specifying these as a comma delimited list as shown above - in the example we'll return rates for EUR, AUD and GBP.
The API returns a RateGroupId value that is what you need to pass to the TX API in order to lock in these rates.
Role RequiredThe token you use to call this API must contain the Forex.Lookup role.
Elevated Rates
During weekends (and potentially other holiday periods) our system uses "elevated rates", which are rates that are slightly higher than the normal FX rate for a transaction. During (but not limited to) weekends, we apply slightly higher margins. If for example you asked for FX rates that span a weekend then you will also receive elevated rates, and dates when these rates apply as shown in the example below...
POST api/forex/7/EUR,AUD,GBP
{
"Currencies": [
{
"Code": "AUD",
"Rates": [
{
"Code": "EUR",
"Elevated": 0.59327,
"Value": 0.59933
},
{
"Code": "GBP",
"Elevated": 0.54524,
"Value": 0.55081
}
]
},
{
"Code": "EUR",
"Rates": [
{
"Code": "AUD",
"Elevated": 1.61879,
"Value": 1.63531
},
{
"Code": "GBP",
"Elevated": 0.90065,
"Value": 0.90984
}
]
},
{
"Code": "GBP",
"Rates": [
{
"Code": "AUD",
"Elevated": 1.76140,
"Value": 1.77937
},
{
"Code": "EUR",
"Elevated": 1.06633,
"Value": 1.07721
}
]
}
],
"ElevatedRates": [
{
"End": "2019-08-26T15:00:00.000Z",
"Start": "2019-08-23T07:00:00.000Z"
}
],
"ExpiresOn": "2019-08-26T09:33:20.21Z",
"RateGroupId": 376
}In the above each FX rate contains an additional parameter, that being the elevated rates that apply during the period(s) shown in the response. So in this instance the elevated rate should be used between 4pm BST on Friday 23rd August to 8am BST on Monday 26th August.
DatesAll dates in our system are recorded in UTC (also known as Zulu time).
The API supports filtering of the currencies that are returned by specifying the set of currencies as a comma-separated list. You can use as many currencies here as you wish.
Using Locked-in rates
Once you have a rate group, you can use it with either immediate or deferred transactions in order to lock in the rates. As an example, the following example uses a rate group to lock in the amount to be received...
POST api/transactionRequests
{
SendValue: 100.00,
SendCurrency: "EUR",
Recipient: {
Name: "B BAGGINS",
RecipientReference: "00005",
Country: "GB",
Currency: "GBP",
Account: {
SortCode: "112233",
AccountNumber: "22233445"
}
},
RateGroupId: 376
}If this TX is posted into the system outside of the elevated rates, then the amount that the recipient will receive (using the example rates above) can be calculated using the regular rate...
amount = 100.00 * 0.9098490868However, if the TX is created within an elevated rate period then the amount received will be...
amount = 100.00 * 0.9006586920As you can see, the elevated rate is lower than the regular rate.
RoundingWe use the following code to round calculations that involve FX rates.
var roundedAmount = Math.Floor(amount * 100.00) / 100.00;
Retrieving Rate Groups
You can also call the API to retrieve the current valid rate groups - this will return a collection of all rate groups that have not yet expired. To do so, just make a GET request as follows...
GET api/forex
[
{
"CreatedOnUtc": "2020-07-29T08:43:58.667Z",
"Currencies": [
"GBP",
"EUR",
"AUD",
"USD"
],
"ExpiresOnUtc": "2020-07-30T08:43:58.637Z",
"RateGroupId": 98
},
{
"CreatedOnUtc": "2020-07-29T08:52:42.32Z",
"Currencies": [
"GBP",
"EUR",
"AUD"
],
"ExpiresOnUtc": "2020-07-30T08:52:42.32Z",
"RateGroupId": 101
},
{
"CreatedOnUtc": "2020-07-30T16:10:06.273Z",
"ExpiresOnUtc": "2020-07-31T16:10:06.253Z",
"RateGroupId": 263
}
]The collection of rate groups is provided for you including the rate group ID's, which you can then use to request all of the rates for a group, or specify when creating a transaction request.
NoteIf, when you created the rate group, you didn't specify a set of currencies, then the API response here will exclude the Currencies collection from the rate group. The last group in the above example shows the response without the Currencies element.
This is a deliberate choice of ours, as it cuts down on the amount of data that is required to be sent back in the API response.
Updated 24 days ago