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}
Content-Type: application/vnd.worldpay.foreignexchange-v1+json

Request

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

Example query string

GET https://try.access.worldpay.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`	Payment method 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	String	1-50
`entity`	leave empty
`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": "R138151125",
            "intent": "MULTI-CURRENCY PRICING",
            "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`	Payment method 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 4217 Valid currency codes.
`targetCurrency`	The credit currency.	ISO 4217 Valid currency codes.
`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
Get FX quote