Create an external contract

Request

Create an external contract to lock a forward FX rate.
For Account Payouts customers only.

Security

basicAuth

Headers

Acceptstringrequired

Example:application/vnd.worldpay.foreignexchange-v1+json

WP-CorrelationIdstring

Optional ID to trace requests, if not provided, it is generated.

Example:15cd16b2-7b82-41cb-9b11-21be9dacad88

Bodyapplication/vnd.worldpay.foreignexchange-v1+json

effectiveDatestringrequired

A future date when the contract becomes available and can be used. Date must be within 30 days in the future.

Example:"2025-12-31T00:00:00.000Z"

sourceCurrencyanyrequired

The transaction currency code. If not supplied, the response contains rates for all source currencies against the target currency.

Example:"USD"

targetCurrencyanyrequired

Your funding (settlement) currency code. If not supplied, the response contains rates for all target currencies against the source currency.

Example:"EUR"

targetAmountanyrequired

The total amount for your forward FX contract and future payout request in the targetCurrency.

Example:1.23

entityanyrequired

6-digit reference given to you by your Worldpay Implementation Manager during the onboarding process

Example:"100001"

customerReferencestring, <= 35 characters

A reference generated by you representing the payer who funds the FX contract.

Example:"Customer 001"

{
  "effectiveDate": "2025-12-31",
  "sourceCurrency": "USD",
  "targetCurrency": "EUR",
  "targetAmount": 1.23,
  "entity": "100001",
  "customerReference": "Customer 001"
}

Responses

OK response if the request is valid

Bodyapplication/vnd.worldpay.foreignexchange-v1+json

contractIdstring

Unique ID of the contract.

Example:"C000000001"

targetAmountstring

Crediting currency code.

Example:"EUR"

sourceAmountstring

Debiting currency code.

Example:"GBP"

statusstring

Status of the contract.

Example:"PENDING"

effectiveDatestring

Datetime representation in UTC of when the contract starts.

Example:"2025-01-01T00:00:00.000Z"

customerReferencestring or null

A reference generated by you representing the payer who funds the FX contract.

Example:"Customer 001"

quoteobject

A collection of quote items.

Response

{
  "contractId": "C000000001",
  "targetAmount": "EUR",
  "sourceAmount": "GBP",
  "status": "PENDING",
  "effectiveDate": "2025-01-01T00:00:00.000Z",
  "customerReference": "Customer 001",
  "quote": {
    "quoteId": "F000000001",
    "sourceCurrency": "EUR",
    "targetCurrency": "GBP",
    "entity": "100001",
    "intent": "FORWARD FX",
    "rateId": "1234567",
    "rate": "1.23456",
    "quoteExpiryTime": "2025-01-01T23:59:59.999Z"
  }
}