Get FX rates

Retrieve an FX Rate pairing.


FX Rate

Authorization: {your_credentials}
Accept: application/vnd.worldpay.foreignexchange-v1+json

Request

  • for Account Payouts customers use: GET https://try.access.worldpay.com/foreignExchange/rates/

  • for Multi Currency Pricing (MCP) customers use: GET https://access.worldpay.com/foreignExchange/rates/

Query string parameters

/foreignExchange/rates?intent=MULTI-CURRENCY%20PRICING&sourceCurrency=EUR&targetCurrency=GBP&entity=PO431501733

Optional string parameters

Field NameDescriptionData Type/FormatMin-Max LengthValidation Criteria
intentPayment method for which rates should be retrieved.
Available values:
For Account Payout customers use:
  • PAYOUT - FX rate for single account payout request
  • FX DEAL - FX rate for internal transfer requests between two consumer accounts
For Multi Currency Pricing (MCP) customers use:
  • MULTI-CURRENCY PRICING - Acquiring processing – New Acquiring Platform (NAP) rates for the customer
  • CONSUMER RATES - NAP rates with added mark-up for the end customer
String1-50
entityFor MULTI-CURRENCY PRICING (MCP) and CONSUMER RATES rates:
  • MCP Account Identifier (PartyID- Merchant Company ID, populated for existing companies only) for which rates should be retrieved. If not supplied, the response contains rates for all identifiers the consumer is entitled to.
For PAYOUT and FX DEAL rates:
  • Leave empty.
String0-30
sourceCurrencyThe transaction currency code. If not supplied, the response contains rates for all source currencies against the target currency.ISO 4217

Valid currency codes.
0-3Must be upper case.
targetCurrencyYour 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-3Must 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 NameDescriptionData Type/Format
rateIdId of the rate request.AN (Length: ≤50)
intentPayment 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)
sourceCurrencyThe debit currency.ISO 4217

Valid currency codes.
targetCurrencyThe credit currency.ISO 4217

Valid currency codes.
bidRateFor PAYOUT and FX DEAL rates:
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.
For MULTI-CURRENCY PRICING and CONSUMER RATES rates:
The bid/purchase rate for the currency pairing.
N
askRateFor PAYOUT and FX DEAL rates:
Not used. For MULTI-CURRENCY PRICING and CONSUMER RATES rates:
The ask/refund rate for the currency pairing.
N
entityIdentity for which rates are retrieved.
For MULTI-CURRENCY PRICING and CONSUMER RATES rates: PartyID - Merchant Company ID, populated for existing companies only.
A
issuedDateDate when the rates were issued.datetime (UTC)
validFromStart date the rates become applicable.datetime (UTC)
validToInclusive 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

ErrorMessageQueryScenario
unauthorizedRequestThe request is unauthorizedUnauthorized request
forbiddenForbidden
urlContainsInvalidValueThe URL contains a value or values that are invalidQuery string parameters are invalid
stringIsTooLongThe length must be 50 characters or fewerIntentLength of intent query string parameter is more than 50 characters
fieldHasInvalidValueInvalid SourceCurrency valueSourceCurrencysourceCurrency is invalid
fieldHasInvalidValueInvalid TargetCurrency valueTargetCurrencytargetCurrency is invalid
fieldHasInvalidValueIntent is not valid for the current ConsumerIntentInvalid value of intent
notFoundNo rates foundRates not found
internalErrorOccurredSomething went wrongInternal error

Next steps


Create FX quote
Get FX quote