Last updated: 05 June 2025 | Change log

Create an FX quote

Account Payout customers only

Lock the FX rate for a specific currency pairing.

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 name	Description	Data type/format	Min-max length	Validation criteria
`entity`	6-digit reference given to you by your Implementation Manager during the onboarding process.	AN	6	Must be six characters.
`intent`	Transaction type (intention) 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) `PAYOUT LIVE RATE` - (real-time FX rate)	String	1-50
`sourceCurrency`	Source currency.	ISO 4217 Valid currency codes.	1-3	Must be all upper-case.
`targetCurrency`	Target currency.	ISO 4217 Valid currency codes.	1-3	Must be uppercase.

Response

Successful response example

{
  "entity": "000696",
  "intent": "PAYOUT",
  "quote": {
    "quoteId": "Q000000BCS",
    "sourceCurrency": "EUR",
    "targetCurrency": "GBP",
    "rateId": "R42813061",
    "rate": 0.77182584,
    "quoteExpiryTime": "2025-03-24T16:07:38.406Z"
  }
}

Successful response fields

Field name	Description	Data type/format
`entity`	6-digit reference given to you by your Implementation Manager during the onboarding process.	AN
`intent`	Transaction type (intention) for which rates are retrieved.	AN
`quoteId`	Unique ID of the quote.	AN
`sourceCurrency`	Debiting currency code	ISO 4217currency codes.
`targetCurrency`	Crediting currency code	ISO 4217 currency codes.
`rateId`	ID of the rate request.	AN
`rate`	The quoted rate.	N
`quoteStartTime`	Datetime representation in UTC of when the quote starts.	datetime (UTC)
`quoteExpiryTime`	Datetime representation in UTC of when the quote expires.	datetime (UTC)
`status`	Status 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

Error	Message	Query	Scenario
`unauthorizedRequest`	The request is unauthorized		Unauthorised request
`forbidden`			Forbidden
`fieldHasInvalidValue`	Invalid SourceCurrency value	SourceCurrency	sourceCurrency is invalid
`fieldHasInvalidValue`	Invalid TargetCurrency value	TargetCurrency	targetCurrency is invalid
`fieldIsMissing`	Missing Intent value	Intent	Missing intent
`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`	Intent is not valid for the current Consumer	Intent	Invalid value of intent
`notFound`			Wrong URL
`internalErrorOccurred`	Something went wrong		Internal error

Next steps

Make a payout using FX quote
Get FX rates
Get FX quote