Last updated: 05 June 2025 | Change log
Coming soon
Account Payout customers only
Lock a forward FX rate for a specific currency pairing and amount for a future date up to 30 days.
Step 1: Create a contract in pending state and retrieve the FX rate.
Start using our FX API by setting your headers.
Authorization: {your_credentials}
Content-Type: application/vnd.worldpay.foreignexchange-v1+jsonPOST https://try.access.worldpay.com/foreignExchange/contract/
{
"effectiveDate": "2024-07-23",
"sourceCurrency": "USD",
"targetCurrency": "EUR",
"targetAmount": "10",
"entity": "000689"
}| 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. |
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. |
targetCurrency | Target currency for the payout. | String | 3 | ISO 4217 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. |
{
"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"
}
}| Field name | Description | Data type/format |
|---|---|---|
entity | 6-digit reference given to you by your 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.
| 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. |
targetCurrency | Crediting currency code. | ISO 4217 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.
Step 2: Activate the contract so you can use it for an account payout with a future date up to 30 days.
PUT https://try.access.worldpay.com/foreignExchange/contract/C0000000BS
{
"status": "ACTIVE",
"entity": "000689"
}| 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. |
contractId | Unique contract ID | String | 11 |
You receive an HTTP response code 204 for a successful request.
{
"errorName": "invalidContract",
"message": "Pending Forward FX Contract has expired"
}| 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 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 using the quoteId returned in your contract creation response