Foreign Exchange Rates API Reference
Foreign Exchange Rates
The Foreign Exchange Rates API provides an easy access to Visa’s currency conversion rate for a given currency pair.
Foreign Exchange Rates v2 - Latest
This API returns Visa's conversion rates for a given currency pair.
- A request with
rateProductCode = "A"returns indicative daily rates that apply to transactions with card as the payment instrument. This is an indicative rate and may be different from the actual rate for settlement of transaction.
You can use the transactionType field to specify whether you want to obtain foreign exchange rates for PULL or PUSH funds transactions:
- PULL – Use when the obtain FX rates for Visa Direct Pull Funds transaction.
- PUSH – Use when the obtain FX rates for Visa Direct Push Funds transaction.
If transactionType is not provided, the API will return FX rates for Visa Direct Push Funds transaction.
A request with
rateProductCode = "B"returns indicative daily rates that apply to transactions with bank-account as the payment instrument. This is an indicative rate and may be different from the actual rate for settlement of transaction.A request with
rateProductCode = "BANK"returns real-time rates that apply to transactions with bank-account as the payment instrument. This option is only available to clients integrating with “Visa Direct Account and Wallet Send API” bundle.A request with
rateProductCode = "WALLET"returns real-time rates that apply to transactions with wallet as the payment instrument. This option is only available to clients integrating with “Visa Direct Account and Wallet Send API” bundle.
Supported Use Cases
- Provide a currency pair and set
quoteIdRequired=truein the FX Request; the response returns a quote ID that can be used on all payout transactions for the same currency pair, until the quote expires. - Provide a currency pair and an amount value in source currency in the FX Request; the response returns a rate and destination amount. This rate and destination amount is only indicative, and not guaranteed to be the same at the time of the payout transaction.
- Provide a currency pair and an amount value in destination currency in the FX Request; the response returns a rate and source amount. This rate and source amount is only indicative, and not guaranteed to be the same at the time of the payout transaction.
Please note that the API specifications have been upgraded from swagger 2.0 to OpenAPI 3.0, and clients who have already been accessing this page for Foreign Exchange Rates V2 API documentation may now see a difference in the documentation rendering. However, the API functionality for “A” & “B” rateProductCodes has not changed.
Request
Request Body schema: application/json
One of:
- FXRequest_using_rateProductCode_A_or_B
- FXRequest_using_rateProductCode_BANK_or_WALLET
One of:
- FXRequest_using_rateProductCode_A_or_B.Request_Source_to_Destination
- FXRequest_using_rateProductCode_A_or_B.Request_Destination_to_Source
| Field | Description |
|---|---|
| destinationCurrencyCode required |
string; ISO 4217 Destination amount currency code in ISO 4217 Numeric code Example: "826" |
| rateProductCode required |
string; indicates which rate source to be used like card based vs account based rates. - A - Card based rates - B - Account based rates Enum: "A", "B" |
| sourceAmount required |
string; [1 .. 13] characters representing the amount in source currency; cannot be 0 or null. Example: "100.55" |
| sourceCurrencyCode required |
string; ISO 4217 Source amount currency code in ISO 4217 Numeric code Example: "840" |
| acquirerDetails | object |
| bin | number Clients of Funds Transfer APIs can provide acquiringBin for reporting purpose. This BIN value is conditionally required. Example: 408999 |
| settlement | object |
| currencyCode | string; ISO 4217 Source Settlement currency code in ISO 4217 Numeric code Example: "840" |
| markupRate | string; [0 .. 6] characters representing the percentage FX mark up rate (<100). Example: "0.07" |
| transactionType | string; indicate that the fx rate is for a push (OCT) or pull (AFT) transaction. If not passed, defaults to push. |
Responses
200
FX response body
Response Schema: application/json
One of:
- FXResponse_using_rateProductCode_A_or_B
- FXResponse_using_rateProductCode_BANK_or_WALLET
| Field | Description |
|---|---|
| conversionRate required |
string; <= 14 characters; this is the Conversion Rate. Note: Excludes markup. Example: "0.07" |
| rateProductCode required |
string; indicates which rate source to be used. - A - Card based rates - B - Account based rates Enum: "A", "B" |
| acquirerDetails | object |
| settlement | object |
| amount | string; the transaction amount in settlement currency. Example: "100.55" |
| conversionRate | string; <= 14 characters; ConversionRate Example: "0.07" |
| currencyCode | string; ISO 4217 settlement amount currency code in ISO 4217 Numeric code Example: "840" |
| destinationAmount | string; required for source-to-destination lookup; the transaction amount in destination currency. Example: "75.85" |
| markupRateApplied | string; [0 .. 6] characters representing the percentage FX mark up rate (<100). Example: "0.07" |
| sourceAmountWithoutMarkup | string; [1 .. 13] characters; excludes markup. Example: "75.85" |
400 Bad Request
Response Schema: application/json
| Field | Description |
|---|---|
| errorResponse required |
object |
| message required |
string; Free form text message describing the error condition. Example: "Missing or Invalid Request Parameters" |
| reason required |
string; custom/business error code Example: "3001" |
| status required |
string; HTTP Status Code Example: "400" |
| details | Array of objects |
| location | string; reference to a field which failed validation Example: "destinationCurrencyCode" |
| message | string; field specific error message Example: "Missing or Invalid content" |
403 Forbidden
Response Schema: application/json
| Field | Description |
|---|---|
| errorResponse required |
object |
| message required |
string; Free form text message describing the error condition. Example: "Product code value B indicating pay-to-account rates is not supported with current subscription." |
| reason required |
string; custom/business error code Example: "4001" |
| status required |
string; HTTP Status Code Example: "403" |
500 Service Unavailable
Response Schema: application/json
| Field | Description |
|---|---|
| errorResponse required |
object |
| message required |
string; Free form text message describing the error condition. Example: "An error occurred while processing the request." |
| reason required |
string; custom/business error code Example: "3004" |
| status required |
string; HTTP Status Code Example: "500" |