Foreign exchange rates API
Use Cross Rivers foreign exchange (FX) rates API to get a foreign currency conversion rate from the card network.
About rate change timing in card networks:
Mastercard. Rates change every day at 14:05 CST in the US. They remain valid for 24 hours. Let's say a transaction occurred on May 1st, 2023 at 3:00 AM CST. The rate that applies to the transaction would be the rate set on April 30th, 2023. That rate covers the period from 14:05 CST on April 30th to 14:05 CST on May 1st.
Visa. Rates change once a day at around 19:00 EST (midnight GMT). Over the weekend, the system uses the rates from Friday.
The endpoint listed in this table is described in detail below.
| Action |
API Call |
Description |
|---|---|---|
| Get international foreign exchange (FX) rate | GET /api/FXRates
|
For a currency pair, gets updated foreign exchange rate information from the card network |
Get International Foreign Exchange (FX) Rate
Returns up-to-date foreign exchange rate information for card-based payments. As a Cross River merchant partner, you do this before making an international transaction.
Add query parameters to filter the response the API returns to all GET calls.
Use pagination to control presentation of your results.
Request attributes
|
requestId string Required The GUID that enables the application to link request with response |
|
sourceCurrency string Required The currency code for the source (monetary) amount. This is a numeric value based on the currencies listed in ISO-4217. For example, if converting from (USD) 840 to (CAD) 124, the value would be 840. |
|
sourceAmount decimal Required The amount of money the payer is sending, in the currency indicated in This value is needed for source-to-destination lookup. Minor currency units after the decimal point must be ≤ (less than or equal to) the defined currency exponent (the digits following the decimal). This field cannot be 0 or null. The field contains between 1 – 13 characters, including a decimal, for example, 100.55. For example:
|
|
destinationCurrency string Required The currency code for the destination (monetary) amount. A numeric value based on the currencies listed in ISO-4217. For example, if converting from (USD) 840 to (CAD) 124, the value would be 124. |
|
markupPercentage decimal Optional The fee the card company charges for an international transaction, for example, 0.07. Note: Not relevant for first release. |
Response attributes
|
requestId string The GUID that enables the application to link request with response |
||||||||
|
markupRateApplied decimal The FX fee rate, as a percentage, for example, 0.07 |
||||||||
|
fxRateNetworkResponses object A list of conversion rates per each relevant card network  child attributes
|
||||||||
Sample request
{
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sourceCurrency": "840",
"sourceAmount": 100,
"destinationCurrency": "826",
"markupPercentage”: 0
}
Sample response
{
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"markupRateApplied": 0.03,
"fxRateNetworkResponses": [
{
"network": visa,
"conversionRate": 1.21,
"destinationAmountWithMarkup": 103,
"destinationAmountWithoutMarkup": 100
},
{
"network": mastercard,
"conversionRate": 1.21,
"destinationAmountWithMarkup": 103,
"destinationAmountWithoutMarkup": 100
}
]
}
