# 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

1. Provide a currency pair and set `quoteIdRequired=true` in 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.
2. 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.
3. 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<br>required | string; ISO 4217<br>Destination amount currency code in ISO 4217 Numeric code<br>Example: "826" |
| rateProductCode<br>required | string; indicates which rate source to be used like card based vs account based rates.<br>- A - Card based rates<br>- B - Account based rates<br>Enum: "A", "B" |
| sourceAmount<br>required | string; [1 .. 13] characters representing the amount in source currency; cannot be 0 or null.<br>Example: "100.55" |
| sourceCurrencyCode<br>required | string; ISO 4217<br>Source amount currency code in ISO 4217 Numeric code<br>Example: "840" |
| acquirerDetails | object | 
| bin | number<br>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<br>Source Settlement currency code in ISO 4217 Numeric code<br>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<br>required | string; <= 14 characters; this is the Conversion Rate. Note: Excludes markup.<br>Example: "0.07" |
| rateProductCode<br>required | string; indicates which rate source to be used.<br>- A - Card based rates<br>- B - Account based rates<br>Enum: "A", "B" |
| acquirerDetails | object |
| settlement | object |
| amount | string; the transaction amount in settlement currency.<br>Example: "100.55" |
| conversionRate | string; <= 14 characters; ConversionRate<br>Example: "0.07" |
| currencyCode | string; ISO 4217<br>settlement amount currency code in ISO 4217 Numeric code<br>Example: "840" |
| destinationAmount | string; required for source-to-destination lookup; the transaction amount in destination currency.<br>Example: "75.85" |
| markupRateApplied | string; [0 .. 6] characters representing the percentage FX mark up rate (<100).<br>Example: "0.07" |
| sourceAmountWithoutMarkup | string; [1 .. 13] characters; excludes markup.<br>Example: "75.85" |

### 400 Bad Request
##### Response Schema: application/json

| Field | Description |
| --- | --- |
| errorResponse<br>required | object |
| message<br>required | string; Free form text message describing the error condition.<br>Example: "Missing or Invalid Request Parameters" |
| reason<br>required | string; custom/business error code<br>Example: "3001" |
| status<br>required | string; HTTP Status Code<br>Example: "400" |
| details | Array of objects | 
| location | string; reference to a field which failed validation<br>Example: "destinationCurrencyCode" |
| message | string; field specific error message<br>Example: "Missing or Invalid content" |

### 403 Forbidden
##### Response Schema: application/json

| Field | Description |
| --- | --- |
| errorResponse<br>required | object |
| message<br>required | string; Free form text message describing the error condition.<br>Example: "Product code value B indicating pay-to-account rates is not supported with current subscription." |
| reason<br>required | string; custom/business error code<br>Example: "4001" |
| status<br>required | string; HTTP Status Code<br>Example: "403" |

### 500 Service Unavailable
##### Response Schema: application/json

| Field | Description |
| --- | --- |
| errorResponse<br>required | object |
| message<br>required | string; Free form text message describing the error condition.<br>Example: "An error occurred while processing the request." |
| reason<br>required | string; custom/business error code<br>Example: "3004" |
| status<br>required | string; HTTP Status Code<br>Example: "500" |