**Last updated**: 05 June 2025 | [**Change log**](/products/fx/changelog/)

# Get FX rates

Retrieve an FX rate pairing.

## Get started

Start using our FX API by [setting your headers](/products/fx#set-your-headers).


```
Authorization: {your_credentials}
Content-Type: application/vnd.worldpay.foreignexchange-v1+json
```

## Request

`GET` `https://try.access.worldpay-bsh.securedataplatform.com/foreignExchange/rates/`

### Example query string

`GET` `https://try.access.worldpay-bsh.securedataplatform.com/foreignExchange/rates/foreignExchange/rates?intent=PAYOUT&sourceCurrency=EUR&targetCurrency=GBP&entity=PO431501733`

### Optional string parameters

| Field name | Description | Data type/format | Min-max length | Validation criteria |
|  --- | --- | --- | --- | --- |
| `intent` | Transaction type (intention) for which rates should be retrieved.Available values:`PAYOUT` - FX rate for single account payout request`FX DEAL` - FX rate for internal transfer requests between two consumer accounts`PAYOUT LIVE RATE` - FX real-time rate | String | 1-50 |  |
| `entity` | 6-digit reference given to you by your Implementation Manager during the onboarding process. |  |  |  |
| `sourceCurrency` | The transaction currency code. If not supplied, the response contains rates for all source currencies against the target currency. | ISO 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-currency-codes). | 0-3 | Must be upper case. |
| `targetCurrency` | Your funding (settlement) currency code. If not supplied, the response contains rates for all target currencies against the source currency. | ISO 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-currency-codes). | 0-3 | Must be upper case. |


## Response

### Successful response example

{
    "rates": [
        {
            "rateId": "R138151125",
            "intent": "PAYOUT",
            "sourceCurrency": "USD",
            "targetCurrency": "EUR",
            "bidRate": 0.93010410,
            "askRate": 0.91169340,
            "entity": "PO4043058348",
            "issuedDate": "2024-05-17T04:00:00.000Z",
            "validFrom": "2024-05-20T04:00:00.000Z",
            "validTo": "2024-05-21T03:59:59.000Z"
        }

    ]
}

### Successful response fields

| Field name | Description | Data type/format |
|  --- | --- | --- |
| `rateId` | Id of the rate request. | AN (Length: ≤50) |
| `intent` | Transaction type (intention) for which rates are retrieved. If an intent was not provided in the request and the retrieved rates are applicable for both PAYOUT and FX DEAL, then the value of the `intent` field in the response is `PAYOUT/FX DEAL`. | AN (Length: ≤50) |
| `sourceCurrency` | The debit currency. | ISO 4217Valid [currency codes](/products/reference/supported-countries-currencies). |
| `targetCurrency` | The credit currency. | ISO 4217Valid [currency codes](/products/reference/supported-countries-currencies). |
| `bidRate` | The bid rate for the currency pairing. This rate is applied when you are selling funds in the source currency by submitting `PAYOUT` or `FX DEAL`. | N |
| `askRate` | Whilst returned, is not used for Payout/ Payin processing. | N |
| `issuedDate` | Date when the rates were issued. | datetime (UTC) |
| `validFrom` | Start date the rates become applicable. | datetime (UTC) |
| `validTo` | Inclusive end date of the rate. | datetime (UTC) |


### Error response example

{
  "errorName": "urlContainsInvalidValue",
  "message": "The URL contains a value or values that are invalid",
  "validationErrors": [
    {
      "errorName": "fieldHasInvalidValue",
      "message": "Invalid SourceCurrency value",
      "queryParameter": "SourceCurrency"
    }
  ]
}
### Error response codes

| Error | Message | Query | Scenario |
|  --- | --- | --- | --- |
| `unauthorizedRequest` | The request is unauthorized |  | Unauthorized request |
| `forbidden` |  |  | Forbidden |
| `urlContainsInvalidValue` | The URL contains a value or values that are invalid |  | Query string parameters are invalid |
| `stringIsTooLong` | The length must be 50 characters or fewer | Intent | Length of intent query string parameter is more than 50 characters |
| `fieldHasInvalidValue` | Invalid SourceCurrency value | SourceCurrency | sourceCurrency is invalid |
| `fieldHasInvalidValue` | Invalid TargetCurrency value | TargetCurrency | targetCurrency is invalid |
| `fieldHasInvalidValue` | Intent is not valid for the current Consumer | Intent | Invalid value of intent |
| `notFound` | No rates found |  | Rates not found |
| `internalErrorOccurred` | Something went wrong |  | Internal error |


**Next steps**

[Create FX quote](/products/fx/create-fxquote)
[Get FX quote](/products/fx/retrieve-fxquote)