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

Coming soon

# Forward FX rates

Account Payout customers only

Lock a forward FX rate for a specific currency pairing and amount for a future date up to 30 days.

## Create a contract with fixed FX rates

**Step 1:** Create a contract in pending state and retrieve the FX rate.

## 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/contract/`

#### Request body


```json
{
  "effectiveDate": "2024-07-23",
  "sourceCurrency": "USD",
  "targetCurrency": "EUR",
  "targetAmount": "10",
  "entity": "000689"
}
```

### Parameters

| Field name | Description | Data type/format | Min-max length | Validation criteria |
|  --- | --- | --- | --- | --- |
| `entity` | 6-digit reference given to you by your Worldpay Implementation Manager during the onboarding process. | AN | 6 | Must be six characters. |
| `effectiveDate` | A future date when the contract becomes available and can be used. | Date | YYYY-MM-DD | Date must be within 30 days in the future. |
| `sourceCurrency` | Source currency for the contract. | String | 3 | [ISO 4217 currency codes](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `targetCurrency` | Target currency for the payout. | String | 3 | [ISO 4217 currency codes](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `targetAmount` | The total amount for your forward FX contract and future payout request in the `targetCurrency`. | Number | 1-10 digits | Must be a positive value up to two decimal places. |


### Response

#### Successful response example


```json
{
    "contractId": "C0000000BS",
    "targetAmount": 10,
    "sourceAmount": 10.927221155755790812556360558,
    "status": "Pending",
    "effectiveDate": "2024-07-23",
    "quote": {
        "quoteId": "Q0000000GH",
        "sourceCurrency": "USD",
        "targetCurrency": "EUR",
        "entity": "000689",
        "intent": "FORWARD FX",
        "rateId": "325990",
        "status": "Pending",
        "rate": 0.91514575,
        "quoteStartTime": "2024-07-23T00:00:00.000Z",
        "quoteExpiryTime": "2024-07-23T23:59:59.999Z"
    }
}
```

#### Successful response fields

| Field name | Description | Data type/format |
|  --- | --- | --- |
| `entity` | 6-digit reference given to you by your Worldpay Implementation Manager during the onboarding process. | AN |
| `contractId` | Unique ID for the new contract. | AN |
| `targetAmount` | The total amount of currency required for this contract. | Numeric (1-10 digits) |
| `sourceAmount` | Source amount is calculated using this formula: sourceAmount = targetAmount / BidRate | Numeric |
| `status` | Status of the contract. `"Pending"` - for a new contract `"Active"` - for an activated contract | AN |
| `effectiveDate` | A future date when the contract becomes available and you can use it. | Date |
| `intent` | Transaction type (intention) for which rates are retrieved. | AN |
| `quoteId` | Unique ID of the quote. | AN |
| `sourceCurrency` | Debiting currency code. | [ISO 4217 currency 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 |
| `status` | Status of the quote. | AN |
| `rate` | The quoted rate. | Numeric |
| `quoteStartTime` | Datetime representation in UTC of when the quote starts. | datetime (UTC) |
| `quoteExpiryTime` | Datetime representation in UTC of when the quote expires. | datetime (UTC) |


Important
Once you have created the contract you must activate it. You can only activate the contract within the first 60 minutes after you have created it.

## Activate contract

**Step 2:** Activate the contract so you can use it for an [account payout](/products/account-payouts/openapi/single-payout) with a future date up to 30 days.

### Request

`PUT` `https://try.access.worldpay-bsh.securedataplatform.com/foreignExchange/contract/C0000000BS`

#### Request body


```json
{
  "status": "ACTIVE",
  "entity": "000689"
}
```

### Parameters

| Field name | Description | Data type/format | Min-max length | Validation criteria |
|  --- | --- | --- | --- | --- |
| `entity` | 6-digit reference given to you by your Worldpay Implementation Manager during the onboarding process. | AN | 6 | Must be six characters. |
| `contractId` | Unique contract ID | String | 11 |  |


### Response

#### Successful response

You receive an `HTTP response code 204` for a successful request.

#### Error response example


```json
{
    "errorName": "invalidContract",
    "message": "Pending Forward FX Contract has expired"
}
```

#### Error response codes

| Error | Message | Scenario |
|  --- | --- | --- |
| `unauthorizedRequest` | The request is unauthorized | Unauthorized request. |
| `forbidden` |  | Forbidden. |
| `fieldIsMissing` | Missing currency/effectiveDate/targetAmount value | Missing currency/effectiveDate/targetAmount. |
| `notFound` |  | Wrong URL. |
| `notFound` | Contract for given input does not exist | Contract for given input does not exist. |
| `internalErrorOccurred` | Something went wrong | Internal error. Please speak to your Worldpay Implementation Manager for further information. |
| `invalidContract` | Pending forward FX contract has expired | You've tried to enable an expired contract. |
| `fieldHasInvalidValue` | EffectiveDate must be within the next 30 days | The date is outside of the 30 day limit of the contract enablement. |


**Next steps**

Make an [account payout](/products/account-payouts/v2/openapi) using the `quoteId` returned in your [contract creation response](#response)