# Create an external contract

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

Endpoint: POST /foreignExchange/contract
Version: 1
Security: basicAuth

## Header parameters:

  - `Accept` (string, required)
    Example: "application/vnd.worldpay.foreignexchange-v1+json"

  - `WP-CorrelationId` (string)
    Optional ID to trace requests, if not provided, it is generated.
    Example: "15cd16b2-7b82-41cb-9b11-21be9dacad88"

## Request fields (application/vnd.worldpay.foreignexchange-v1+json):

  - `effectiveDate` (string, required)
    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"

  - `sourceCurrency` (any, required)
    The transaction currency code. If not supplied, the response contains rates for all source currencies against the target currency.
    Example: "USD"

  - `targetCurrency` (any, required)
    Your funding (settlement) currency code. If not supplied, the response contains rates for all target currencies against the source currency.
    Example: "EUR"

  - `targetAmount` (any, required)
    The total amount for your forward FX contract and future payout request in the targetCurrency.
    Example: 1.23

  - `entity` (any, required)
    6-digit reference given to you by your Implementation Manager during the onboarding process
    Example: "100001"

  - `customerReference` (string)
    A reference generated by you representing the payer who funds the FX contract.
    Example: "Customer 001"

## Response 200 fields (application/vnd.worldpay.foreignexchange-v1+json):

  - `contractId` (string)
    Unique ID of the contract.
    Example: "C000000001"

  - `targetAmount` (string)
    Crediting currency code.
    Example: "EUR"

  - `sourceAmount` (string)
    Debiting currency code.
    Example: "GBP"

  - `status` (string)
    Status of the contract.
    Example: "PENDING"

  - `effectiveDate` (string)
    Datetime representation in UTC of when the contract starts.
    Example: "2025-01-01T00:00:00.000Z"

  - `customerReference` (string,null)
    A reference generated by you representing the payer who funds the FX contract.
    Example: "Customer 001"

  - `quote` (array)
    A collection of quote items.

  - `quote.quoteId` (string)
    Unique quote id.
    Example: "F000000001"

  - `quote.sourceCurrency` (string)
    The debit currency.
    Example: "EUR"

  - `quote.targetCurrency` (string)
    The credit currency.
    Example: "GBP"

  - `quote.entity` (string)
    6-digit reference given to you by your Implementation Manager during the onboarding process.
    Example: "100001"

  - `quote.intent` (string)
    Payment method (intent) for which rates are retrieved.
    Example: "FORWARD FX"

  - `quote.rateId` (string)
    Unique rate id.
    Example: "1234567"

  - `quote.rate` (string)
    Rate amount.
    Example: "1.23456"

  - `quote.quoteExpiryTime` (string)
    Quote start time.
    Example: "2025-01-015T23:59:59.999Z"

## Response 400 fields (application/vnd.worldpay.foreignexchange-v1+json):

  - `validationErrors` (array, required)
    Object containing details of validation errors occurred

  - `validationErrors.jsonPath` (string, required)
    Parameter for which the error occurred

  - `validationErrors.errorName` (string, required)
    Unique name of the validation error

  - `validationErrors.message` (string, required)
    Error description message

  - `errorName` (string, required)
    The unique error name

## Response 401 fields (application/vnd.worldpay.foreignexchange-v1+json):

  - `errorName` (string, required)
    The unique error name

  - `message` (string, required)
    Error description message

## Response 403 fields (application/vnd.worldpay.foreignexchange-v1+json):

  - `errorName` (string, required)
    The unique error name

  - `message` (string, required)
    Error description message

## Response 404 fields (application/vnd.worldpay.foreignexchange-v1+json):

  - `errorName` (string, required)
    The unique error name

  - `message` (string, required)
    Error description message

## Response 500 fields (application/vnd.worldpay.foreignexchange-v1+json):

  - `errorName` (string, required)
    The unique error name

  - `message` (string, required)
    Error description message