**Last updated**: 05 June 2025 | [**Change log**](/products/fx/changelog/)

# 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](/products/fx#set-your-headers).


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

## Request

`POST` `https://try.access.worldpay-bsh.securedataplatform.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 4217Valid [currency codes](/products/reference/supported-countries-currencies). | 1-3 | Must be all upper-case. |
| `targetCurrency` | Target currency. | ISO 4217Valid [currency codes](/products/reference/supported-countries-currencies). | 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](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `targetCurrency` | Crediting currency code | [ISO 4217 currency codes](/products/reference/supported-countries-currencies#iso-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](/products/account-payouts/)
[Get FX rates](/products/fx/fxrate)
[Get FX quote](/products/fx/retrieve-fxquote)