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 Name	Description	Data Type/Format	Min-Max Length	Validation Criteria
`entity`	Unique ID given to you during the onboarding process.	AN	6	Must be six characters.
`intent`	Payment 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)`	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": "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 Name	Description	Data Type/Format
`entity`	Unique ID given to you during the onboarding process.	AN
`intent`	Payment method (intent) 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

Get FX rates
Get FX quote