Last Updated: 22 July 2024 | Change Log
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.
Authorization: {your_credentials} Content-Type: application/vnd.worldpay.foreignexchange-v1+json
Request
POST https://try.access.worldpay.com/foreignExchange/contract/
Request body
{ "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 | Unique ID given to you 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. |
Response
Successful response example
{ "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 | Unique ID given to you 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 | Payment method (intent) 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 enable it. You can only enable the contract within the first 60 minutes after you have created it.
Enable contract
Step 2: Enable the contract so you can use it for an account payout with a future date up to 30 days.
Request
POST https://try.access.worldpay.com/foreignExchange/contract/C0000000BS/enable
Request body
{ "entity": "000689" }
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. |
contractId | Unique contract ID | String | 11 |
Response
Successful response
You receive an HTTP response code 204 for a successful request.
Error response example
{ "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 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