Last Updated: 09 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.

Set your header


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

Request

POST https://try.access.worldpay.com/foreignExchange/contract/

Request body

{
    "effectiveDate": "2024-06-15",
    "sourceCurrency": "SEK",
    "targetCurrency":"EUR",
    "targetAmount": 444,
    "entity": "001234"
}

Parameters

Field nameDescriptionData type/FormatMin-Max lengthValidation criteria
entityUnique ID given to you during the onboarding process.AN6Must be six characters.
effectiveDateA future date when the contract becomes available and can be used.DateYYYY-MM-DDDate must be within 30 days in the future.
sourceCurrencySource currency for the contract.String3ISO 4217 currency codes.
targetCurrencyTarget currency for the payout.String3ISO 4217 currency codes.
targetAmountThe total amount for your forward FX contract and future payout request in the targetCurrency.Number1-10 digitsMust be a positive value up to two decimal places.

Response

Successful response example

{
    "contractId": "C0000000X1",
    "targetAmount": 444,
    "sourceAmount": 5000,		
    "status": "Pending",
    "effectiveDate": "2024-06-15",
    "quote": {
        "quoteId": "Q0000000A5",
        "sourceCurrency": "SEK",
        "targetCurrency": "EUR",
        "entity": "001234",      
        "quoteExpiryTime": "2024-06-04T24:59:59Z",
        "intent": "FORWARD FX",
        "rateId": "R179173740",
        "rate": " 0.08900000 "
    }
}

Successful response fields

Field NameDescriptionData Type/Format
entityUnique ID given to you during the onboarding process.AN
contractIdUnique ID for the new contract.AN
targetAmountThe total amount of currency required for this contract.Numeric (1-10 digits)
sourceAmountSource amount is calculated using this formula: sourceAmount = targetAmount / BidRateNumeric
statusStatus of the contract.
  • "Pending" - for a new contract
  • "Active" - for an enabled contract
AN
effectiveDateA future date when the contract becomes available and you can use it.Date
intentPayment method (intent) for which rates are retrieved.AN
quoteIdUnique ID of the quote.AN
sourceCurrencyDebiting currency code.ISO 4217 currency codes.
targetCurrencyCrediting currency code.ISO 4217 currency codes.
rateIdID of the rate request.AN
rateThe quoted rate.Numeric
quoteExpiryTimeDatetime representation in UTC of when the quote expires.Date/time (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

PATCH https://try.access.worldpay.com/foreignExchange/contract/{C0000000X1}/enable

Request body

{
    "entity": "001234"
}

Parameters

Field NameDescriptionData Type/FormatMin-Max LengthValidation Criteria
entityUnique ID given to you during the onboarding process.AN6Must be six characters.
contractIdUnique contract IDString11

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

ErrorMessageScenario
unauthorizedRequestThe request is unauthorizedUnauthorized request.
forbiddenForbidden.
fieldIsMissingMissing currency/effectiveDate/targetAmount valueMissing currency/effectiveDate/targetAmount.
notFoundWrong URL.
notFoundContract for given input does not existContract for given input does not exist.
internalErrorOccurredSomething went wrongInternal error.
invalidContractPending forward FX contract has expiredEnabling an expired contract.
fieldHasInvalidValueEffectiveDate must be within the next 30 daysWrong effective date.

Next Steps


Make an account payout using the quoteId returned in your contract creation response