Last Updated: 22 July 2024 | Change Log

Get FX rates

Retrieve an FX rate pairing.

Get Started

Start using our FX API by setting 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`	Payment method 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 customer If 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 4217 Valid 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 4217 Valid 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`	Payment method for which rates are retrieved.	AN (Length: ≤50)
`sourceCurrency`	The debit currency.	ISO 4217 Valid currency codes.
`targetCurrency`	The credit currency.	ISO 4217 Valid currency codes.
`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.
`fieldHasInvalidValue`	Invalid TargetCurrency value	You've used and invalid currency code.
`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.