**Last updated**: 05 June 2025 | [**Change log**](/products/fx/changelog/)

# 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](/products/fx#set-your-headers).


```
Authorization: {your_credentials}
Accept: application/vnd.worldpay.foreignexchange-v1+json
```

### Request

`PUT` `https://access.worldpay-bsh.securedataplatform.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 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-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 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-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](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `fieldHasInvalidValue` | Invalid TargetCurrency value | You've used and invalid [currency code](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `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-bsh.securedataplatform.com/foreignExchange/markup/`

#### Example query string

`GET` `https://access.worldpay-bsh.securedataplatform.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 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-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 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-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 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `targetCurrency` | The credit currency. | ISO 4217Valid [currency codes](/products/reference/supported-countries-currencies#iso-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](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `InvalidTargetCurrency value` | Invalid TargetCurrency value | You've used and invalid [currency code](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `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**

[Get FX MCP Rates](/products/fx/fxrate-mcp)