Passed

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
Languages
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.

Security
basicAuth
Query
intentstring[ 1 .. 50 ] characters

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

Enum"PAYOUT""FX DEAL""MULTI-CURRENCY PRICING""CONSUMER RATES""PAYOUT LIVE RATE"
entitystring= 6 characters

For Multi-Currency Pricing customers, entity is MCP Account Identifier (PartyID- Merchant Company ID, Unique ID given to you during the onboarding process.) for which rates should be retrieved.

For Account Payout customers, entity is 6-digit reference given to you by your Implementation Manager 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

6-digit reference given to you by your Implementation Manager 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 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
entitystringrequired

6-digit reference given to you by your Implementation Manager 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""PAYOUT LIVE RATE"
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

6-digit reference given to you by your Implementation Manager 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.

Security
basicAuth
Query
entitystring<= 6 charactersrequired

6-digit reference given to you by your Implementation Manager 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

6-digit reference given to you by your Implementation Manager 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.

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

6-digit reference given to you by your 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"
application/vnd.worldpay.foreignexchange-v1+json
{
  "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-01"
customerReferencestring or null

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

Example: "Customer 001"
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

6-digit reference given to you by your Implementation Manager 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",
  "customerReference": "Customer 001",
  "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.

Security
basicAuth
Path
contractIdstring[ 1 .. 50 ] charactersrequired

Unique ID of the contract.

Example: 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

6-digit reference given to you by your Implementation Manager 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.

Security
basicAuth
Path
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: 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.

Security
basicAuth
Path
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: 100001
Query
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

6-digit reference given to you by your Implementation Manager 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"
}