Last Updated: 22 July 2024 | Change Log

Create an FX quote

Account Payout customers only

Lock the FX rate for a specific currency pairing for up to 48 hours.


Get Started

Start using our FX API by setting your headers.

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

Request

POST https://try.access.worldpay.com/foreignExchange/quote/

Request body

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

Mandatory parameters

Field NameDescriptionData Type/FormatMin-Max LengthValidation Criteria
entityUnique ID given to you during the onboarding process.AN6Must be six characters.
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)
String1-50
sourceCurrencySource currency.ISO 4217

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

Valid currency codes.
1-3Must be uppercase.

Response

Successful response example

{
    "entity": "000055",
    "intent": "PAYOUT",
    "quote": {
        "quoteId": "Q0000000RH",
        "sourceCurrency": "EUR",
        "targetCurrency": "ARS",
        "rateId": "R139884",
        "rate": 62.83084438,
        "quoteStartTime": "2024-07-23T06:41:15.773Z",
        "quoteExpiryTime": "2024-07-24T23:59:59.999Z",
        "status": "Active"
    }
}

Successful response fields

Field NameDescriptionData Type/Format
entityUnique ID given to you during the onboarding process.AN
intentPayment method (intent) for which rates are retrieved.AN
quoteIdUnique ID of the quote.AN
sourceCurrencyDebiting currency codeISO 4217currency codes.
targetCurrencyCrediting currency codeISO 4217 currency codes.
rateIdID of the rate request.AN
rateThe quoted rate.N
quoteStartTimeDatetime representation in UTC of when the quote starts.datetime (UTC)
quoteExpiryTimeDatetime representation in UTC of when the quote expires.datetime (UTC)
statusStatus of the quote.AN

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

ErrorMessageQueryScenario
unauthorizedRequestThe request is unauthorizedUnauthorised request
forbiddenForbidden
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