Get FX rates

FX API (1)

Authentication Header

  Authorization: {your_credentials}

Replace {your_credentials} with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.

You must use the Authorization header for any request you send to our FX APIs, unless you are using client certificate authenticating with SSL/TLS.

Accept Header

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

We use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our FX APIs.

DNS Whitelisting

Whitelist the following URLs:

https://try.access.worldpay.com/
https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting. When you make a request within Access Worldpay, you should always cache the response returned.

Download OpenAPI description

openapi.json

openapi.yaml

Servers

testing (try) - Account Payouts customers only

https://try.access.worldpay.com/

live

https://access.worldpay.com/

Get FX rates

Request

Retrieve an FX rate for a particular payment method.

Query

intentstring[ 1 .. 50 ] characters

Transaction type (intention) for which rates should be retrieved.

Enum"PAYOUT""FX DEAL""MULTI-CURRENCY PRICING""CONSUMER RATES"

entitystring= 6 characters

Your unique 6-digit ID given to you during the onboarding process.

Example: entity=100001

sourceCurrencystring= 3 characters^[A-Z]*$

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

Example: sourceCurrency=USD

targetCurrencystring= 3 characters^[A-Z]*$

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

Example: targetCurrency=EUR

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

No request payload

Responses

OK response if the request is valid

Bodyapplication/vnd.worldpay.foreignexchange-v1+json

ratesArray of objects

A collection of rates items.

rateIdstring

Unique reference for the rate.

Example: "R12345678"

intentstring

Transaction type (intention) for which rates should be retrieved.

Example: "PAYOUT"

sourceCurrencystring

The debit currency.

Example: "EUR"

targetCurrencystring

The credit currency.

Example: "GBP"

bidRatenumber(double)

The buy/refund rate for the currency pairing.

Example: "1.23456789"

askRatenumber(double)

The sell/purchase rate for the currency pairing.

Example: "1.23456789"

entitynumber

Your unique 6-digit ID given to you during the onboarding process.

Example: "100001"

issuedDatestring(date-time)

The posting date of the specific statement item.

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

validFromstring(date-time)

Validation date from.

Example: "2025-01-10T12:00:00.000Z"

validTostring(date-time)

Validation date to.

Example: "2025-01-10T12:00:00.000Z"

Response

application/vnd.worldpay.foreignexchange-v1+json

{
  "rates": [
    {
      "rateId": "R12345678",
      "intent": "PAYOUT",
      "sourceCurrency": "EUR",
      "targetCurrency": "GBP",
      "bidRate": "1.23456789",
      "askRate": "1.23456789",
      "entity": "100001",
      "issuedDate": "2025-01-01T12:00:00.000Z",
      "validFrom": "2025-01-10T12:00:00.000Z",
      "validTo": "2025-01-10T12:00:00.000Z"
    }
  ]
}

Create FX quote

Request

Lock the FX rate for a specific currency pairing for up to 48 hours.
For Account Payouts customers only.

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

entitystringrequired

Your unique 6-digit ID given to you during the onboarding process.

Example: "100001"

intentstringrequired

Transaction type (intention) for which rates should be retrieved.

Enum"PAYOUT""FX DEAL""MULTI-CURRENCY PRICING""CONSUMER RATES"

sourceCurrencystringrequired

The debit currency.

Example: "USD"

targetCurrencystringrequired

The credit currency.

Example: "EUR"

application/vnd.worldpay.foreignexchange-v1+json

{
  "entity": "100001",
  "intent": "PAYOUT",
  "sourceCurrency": "USD",
  "targetCurrency": "EUR"
}

Responses

OK response if the request is valid

Bodyapplication/vnd.worldpay.foreignexchange-v1+json

entitystring

Your unique 6-digit ID given to you during the onboarding process.

Example: "100001"

intentstring

Transaction type (intention) for which rates should be retrieved.

Example: "PAYOUT"

quoteArray of objects

A collection of account statement items.

quoteIdstring

Unique quote id.

Example: "Q000000001"

sourceCurrencystring

The debit currency.

Example: "EUR"

targetCurrencystring

The credit currency.

Example: "GBP"

rateIdstring

Unique rate id.

Example: "12345678"

ratestring

Rate amount

Example: "1.2345"

quoteExpiryTimestring

Quote start time.

Example: "2025-01-10T12:00:00.000Z"

Response

application/vnd.worldpay.foreignexchange-v1+json

{
  "entity": "100001",
  "intent": "PAYOUT",
  "quote": [
    {
      "quoteId": "Q000000001",
      "sourceCurrency": "EUR",
      "targetCurrency": "GBP",
      "rateId": "12345678",
      "rate": "1.2345",
      "quoteExpiryTime": "2025-01-10T12:00:00.000Z"
    }
  ]
}

Retrieve an FX quote

Request

Retrieving an existing FX quote.
For Account Payouts customers only.

Query

entitystring<= 6 charactersrequired

Your unique 6-digit ID given to you during the onboarding process.

Example: entity=100001

quoteIdstring[ 1 .. 50 ] charactersrequired

Unique ID of the quote.

Example: quoteId=Q000000001

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

No request payload

Responses

OK response if the request is valid

Bodyapplication/vnd.worldpay.foreignexchange-v1+json

entitystring

Your unique 6-digit ID given to you during the onboarding process.

Example: "100001"

intentstring

Transaction type (intention) for which rates should be retrieved.

Example: "PAYOUT"

quoteArray of objects

A collection of quote items.

quoteIdstring

Unique quote id.

Example: "Q000000001"

sourceCurrencystring

The debit currency.

Example: "EUR"

targetCurrencystring

The credit currency.

Example: "GBP"

rateIdstring

Unique rate id.

Example: "12345678"

ratestring

Rate amount

Example: "1.2345"

quoteExpiryTimestring

Quote start time.

Example: "2025-01-10T12:00:00.000Z"

Response

application/vnd.worldpay.foreignexchange-v1+json

{
  "entity": "100001",
  "intent": "PAYOUT",
  "quote": [
    {
      "quoteId": "Q000000001",
      "sourceCurrency": "EUR",
      "targetCurrency": "GBP",
      "rateId": "12345678",
      "rate": "1.2345",
      "quoteExpiryTime": "2025-01-10T12:00:00.000Z"
    }
  ]
}

Create an external contract

Request

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

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-31"

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

Your unique 6-digit ID given to you during the onboarding process.

Example: "100001"

application/vnd.worldpay.foreignexchange-v1+json

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

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-01"

quoteArray of objects

A collection of quote items.

quoteIdstring

Unique quote id.

Example: "F000000001"

sourceCurrencystring

The debit currency.

Example: "EUR"

targetCurrencystring

The credit currency.

Example: "GBP"

entitystring

Your unique 6-digit ID given to you during the onboarding process.

Example: "100001"

intentstring

Payment method (intent) for which rates are retrieved.

Example: "FORWARD FX"

rateIdstring

Unique rate id.

Example: "1234567"

ratestring

Rate amount.

Example: "1.23456"

quoteExpiryTimestring

Quote start time.

Example: "2025-01-015T23:59:59.999Z"

Response

application/vnd.worldpay.foreignexchange-v1+json

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

Activate or cancel contract

Request

Enable a contract to use locked in FX rates in an Account Payout.
For Account Payouts customers only.

Query

contractIdstring[ 1 .. 50 ] charactersrequired

Unique ID of the contract.

Example: contractId=C000000001

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

statusstringrequired

New status of the contract.

Enum"ACTIVE""CANCELLED"

entitystringrequired

Your unique 6-digit ID given to you during the onboarding process.

Example: "100001"

application/vnd.worldpay.foreignexchange-v1+json

{
  "status": "ACTIVE",
  "entity": "100001"
}

Responses

OK response if the request is valid

Response

No content

Add a markup to your FX rate

Request

Adding a markup to an existing FX rate.
For MCP customers only.

Query

entitystringrequired

MCP Account Identifier (PartyID- Merchant Company ID, unique 6-digit ID given to you during the onboarding process) for which rates should be retrieved.

Example: entity=100001

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

sourceCurrencyanyrequired

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

Example: "AUD"

targetCurrencyanyrequired

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

Example: "GBP"

markupanyrequired

The additional margin percentage set up on FX rates.

Example: 1.23

application/vnd.worldpay.foreignexchange-v1+json

{
  "sourceCurrency": "AUD",
  "targetCurrency": "GBP",
  "markup": 1.23
}

Responses

OK response if the request is valid

Response

No content

Retrieve markup

Request

Retrieving an existing markup for a specific FX rate.
For MCP customers only.

Query

entitystring<= 6 charactersrequired

MCP Account Identifier (PartyID- Merchant Company ID, unique 6-digit ID given to you during the onboarding process.) for which rates should be retrieved.

Example: entity=100001

sourceCurrencystring= 3 characters^[A-Z]*$

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

Example: sourceCurrency=USD

targetCurrencystring= 3 characters^[A-Z]*$

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

Example: targetCurrency=EUR

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

No request payload

Responses

OK response if the request is valid

Bodyapplication/vnd.worldpay.foreignexchange-v1+json

sourceCurrencystring

The debit currency.

Example: "EUR"

targetCurrencystring

The credit currency.

Example: "GBP"

paymentMethodstring

Payment method.

Example: "ENDCONSUMERRATES"

entitystring

Your unique 6-digit ID given to you during the onboarding process.

Example: "100001"

valuestring

Markup value setup.

Example: "1.234"

Response

application/vnd.worldpay.foreignexchange-v1+json

{
  "sourceCurrency": "EUR",
  "targetCurrency": "GBP",
  "paymentMethod": "ENDCONSUMERRATES",
  "entity": "100001",
  "value": "1.234"
}

FX API (1)

Get FX rates

Request

Responses

Do you like our page?

Create FX quote

Request

Responses

Do you like our page?

Retrieve an FX quote

Request

Responses

Do you like our page?

Create an external contract

Request

Responses

Do you like our page?

Activate or cancel contract

Request

Responses

Do you like our page?

Add a markup to your FX rate

Request

Responses

Do you like our page?

Retrieve markup

Request

Responses

Do you like our page?