Create an FX quote

Locking the FX Rate for a specific currency pairing for a certain period of time.


This service is available for use as part of the future enhancements to FX API in 2024.

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



Request body

  "entity": "000055",
  "intent": "PAYOUT",
  "sourceCurrency": "EUR",
  "targetCurrency": "ARS"

Mandatory parameters

Field NameDescriptionData Type/FormatMin-Max LengthValidation Criteria
entityUnique consumer ID given during the onboarding process. Indicates the consumer for whom the quote is for.String6-6
intentPayment method (intent) 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)
sourceCurrencySource currency.ISO 4217

Valid currency codes.
1-3Must be all upper-case.
targetCurrencyTarget currency.ISO 4217

Valid currency codes.
1-3Must be uppercase.


Successful response example

    "entity": "000055",
    "intent": "PAYOUT",
    "quote": {
        "quoteId": "Q0000000BJ",
        "sourceCurrency": "EUR",
        "targetCurrency": "ARS",
        "rateId": "R1",
        "rate": 70.82084705,
        "quoteExpiryTime": "2023-04-21T23:59:59.000Z"

Successful response fields

Field NameDescriptionData Type/Format
entityConsumer for whom the quote is for.A
intentPayment method (intent) for which rates are retrieved.AN
quoteIdUnique id of the quote.AN
sourceCurrencyThe currency code that is debited currency.ISO 4217

Valid currency codes.
targetCurrencyThe currency code that is credited currency.ISO 4217

Valid currency codes.
rateIdId of the rate request.AN
rateThe quoted rate.N
quoteExpiryTimeDatetime representation in UTC of when the quote will expire.datetime (UTC)

Error response example

    "errorName": "bodyDoesNotMatchSchema",
    "message": "The json body provided does not match the expected schema",
    "validationErrors": [
            "errorName": "fieldIsMissing",
            "message": "Missing TargetCurrency value",
            "jsonPath": "TargetCurrency"

Error response codes

unauthorizedRequestThe request is unauthorizedUnauthorised request
fieldHasInvalidValueInvalid SourceCurrency valueSourceCurrencysourceCurrency is invalid
fieldHasInvalidValueInvalid TargetCurrency valueTargetCurrencytargetCurrency is invalid
fieldIsMissingMissing Intent valueIntentMissing intent
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
fieldHasInvalidValueIntent is not valid for the current ConsumerIntentInvalid value of intent
notFoundWrong URL
internalErrorOccurredSomething went wrongInternal error

Next steps

Get FX rates
Get FX quote