Last Updated: 05 June 2025 | Change Log
Markup FX API
Multi-Currency Pricing customers only
Add a markup to your FX rate
Get Started
Start using our FX API by setting your headers.
Authorization: {your_credentials}
Accept: application/vnd.worldpay.foreignexchange-v1+jsonRequest
PUT https://access.worldpay.com/foreignExchange/markup/
Request body
{
"SourceCurrency": "USD",
"TargetCurrency": "EUR",
"Markup": 0.38800000
}
Parameters
| Field name | Description | Data type/Format | M/O/C | Min-Max length | Validation criteria |
|---|---|---|---|---|---|
entity | MCP Account Identifier (PartyID- Merchant Company ID, Unique ID given to you during the onboarding process.) for which rates should be retrieved. | AN | M | 6 | Must be six characters. |
SourceCurrency | The transaction currency code. If not supplied, the response contains rates for all source currencies against the target currency. | ISO 4217 Valid currency codes. | O | 0-3 | Must be upper case. |
TargetCurrency | Your funding (settlement) currency code. If not supplied, the response contains rates for all target currencies against the source currency. | ISO 4217 Valid currency codes. | O | 0-3 | Must be upper case. |
Markup | The additional margin percentage set up on FX rates. | N | M | The value must be in decimal format |
Response
Successful response
You receive an HTTP response code 200 for a successful request.
Error response example
{
"errorName": "notFound",
"message": "Not found"
}Error response codes
| Error | Message | Scenario |
|---|---|---|
unauthorizedRequest | The request is unauthorized | Unauthorized request. Your credentials are incorrect. |
forbidden | Forbidden | No permission to access. |
urlContainsInvalidValue | The URL contains a value or values that are invalid | Query string parameters are invalid. |
fieldHasInvalidValue | Invalid SourceCurrency value | You've used and invalid currency code. |
fieldHasInvalidValue | Invalid TargetCurrency value | You've used and invalid currency code. |
fieldIsMissing | Missing Markup value | Markup field is missing. |
notFound | Not found | entity, sourceCurrency or targetCurrency is not found. |
internalErrorOccurred | Something went wrong | Internal error. Please speak to your Implementation Manager for further information. |
Retrieve the markup applied on entity
Request
GET https://access.worldpay.com/foreignExchange/markup/
Example query string
GET https://access.worldpay.com/foreignExchange/markup/foreignExchange/markup/PO4043058348?sourceCurrency=USD&targetCurrency=EUR
Parameters
| Field Name | Description | Data Type/Format | Min-Max Length | Validation Criteria |
|---|---|---|---|---|
entity | MCP Account Identifier (PartyID- Merchant Company ID, Unique ID given to you during the onboarding process.) for which rates should be retrieved. | String | 0-30 | |
sourceCurrency | The transaction currency code. If not supplied, the response contains rates for all source currencies against the target currency. | ISO 4217 Valid currency codes. | 0-3 | Must be upper case. |
targetCurrency | Your funding (settlement) currency code. If not supplied, the response contains rates for all target currencies against the source currency. | ISO 4217 Valid currency codes. | 0-3 | Must be upper case. |
Response
Successful response example
{
"sourceCurrency": "USD",
"targetCurrency": "EUR",
"paymentMethod": "ENDCONSUMERRATES",
"entity": "PO4043058348",
"value": 0.38800000
}Successful response fields
| Field Name | Description | Data Type/Format |
|---|---|---|
sourceCurrency | The debit currency. | ISO 4217 Valid currency codes. |
targetCurrency | The credit currency. | ISO 4217 Valid currency codes. |
entity | MCP Account Identifier (PartyID- Merchant Company ID, Unique ID given to you during the onboarding process.) for which rates should be retrieved. | AN |
Value | Markup value setup | N |
Error response example
{
"errorName": "notFound",
"message": "Not found"
}Error response codes
| Error | Message | Scenario |
|---|---|---|
unauthorizedRequest | The request is unauthorized | Unauthorized request. Your credentials are incorrect. |
forbidden | Forbidden | No permission to access. |
urlContainsInvalidValue | The URL contains a value or values that are invalid | Query string parameters are invalid. |
InvalidSourceCurrency value | Invalid SourceCurrency value | You've used and invalid currency code. |
InvalidTargetCurrency value | Invalid TargetCurrency value | You've used and invalid currency code. |
notFound | Not found | entity, sourceCurrency or targetCurrency is not found. |
internalErrorOccurred | Something went wrong | Internal error. Please speak to your Implementation Manager for further information. |
Next steps