**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}
Accept: application/vnd.worldpay.foreignexchange-v1+json
```

## Request

`GET` `https://access.worldpay.com/foreignExchange/rates/`

Note
Requests must be sent to our production URL if you are a Multi-Currency Pricing customer.

### Example query string

`GET` `https://access.worldpay.com/foreignExchange/rates/foreignExchange/rates?intent=MULTI-CURRENCY%20PRICING&sourceCurrency=USD&targetCurrency=EUR&entity=PO4043058348`

### Optional string parameters

| Field name | Description | Data type/format | Min-max length | Validation criteria |
|  --- | --- | --- | --- | --- |
| `intent` | Transaction type (intention) for which rates should be retrieved.**Values:**`MULTI-CURRENCY PRICING` - Acquiring processing - New Acquiring Platform (NAP) rates for the customer`CONSUMER RATES` - NAP rates with added markup for the end customerIf not supplied, the response contains rates for both intent | String | 1-50 |  |
| `entity` | MCP Account Identifier (PartyID- Merchant Company ID, Unique ID given to you during the onboarding process.) for which rates should be retrieved. | String | 0-30 |  |
| `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": "R301887",
            "intent": "CONSUMER RATES",
            "sourceCurrency": "AED",
            "targetCurrency": "GBP",
            "bidRate": 4.17634728,
            "askRate": 4.22019872,
            "entity": "PO4031501653",
            "issuedDate": "2023-05-31T04:00:00.000Z",
            "validFrom": "2023-05-31T04:00:00.000Z",
            "validTo": "2023-06-01T03: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. | 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/refund rate for the currency pairing. | N |
| `askRate` | The ask/purchase rate for the currency pairing. | N |
| `entity` | PartyID - Merchant Company ID, populated for existing companies only.(Unique ID given to you during the onboarding process.) | A |
| `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 | Scenario |
|  --- | --- | --- |
| `unauthorizedRequest` | The request is unauthorized | Unauthorized request. Your credentials are incorrect. |
| `forbidden` | Forbidden | No permission to access. |
| `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 |
| `fieldHasInvalidValue` | Invalid SourceCurrency value | You've used and invalid [currency code](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `fieldHasInvalidValue` | Invalid TargetCurrency value | You've used and invalid [currency code](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `fieldHasInvalidValue` | Intent is not valid for the current Consumer | Invalid value of `intent`. |
| `notFound` | Not found | `entity`, `sourceCurrency` or `targetCurrency` is not found. |
| `internalErrorOccurred` | Something went wrong | Internal error. Please speak to your Implementation Manager for further information. |