---
title: "Configuration-based surcharge"
description: "Define rules for surcharge amounts or percentages, and when to apply them."
url: "https://docs.adyen.com/platforms/in-person-payments/surcharge/configuration"
source_url: "https://docs.adyen.com/platforms/in-person-payments/surcharge/configuration.md"
canonical: "https://docs.adyen.com/platforms/in-person-payments/surcharge/configuration"
last_modified: "2026-06-01T15:33:15+02:00"
language: "en"
---

# Configuration-based surcharge

Define rules for surcharge amounts or percentages, and when to apply them.

[View source](/platforms/in-person-payments/surcharge/configuration.md)

Using Management API settings, you can configure surcharge rules for your Adyen company or merchant account, store, or individual terminals. Your rules need to take into account all applicable compliance requirements and aspects such as payment method (card brand), funding source, issuing country, and currency.

Based on the rules you configured, surcharges are then automatically calculated and applied to your in-person payments. In your payment requests, you can use split instructions to define how to book the surcharge amount.

Depending on your [use case](/platforms/in-person-payments/surcharge#surcharge-methods), you can combine configuration-based surcharge with [dynamic surcharge](/platforms/in-person-payments/surcharge/dynamic).

## Requirements

In addition to the [general requirements](/platforms/in-person-payments#requirements) for in-person payments with an Adyen for Platforms integration and the general [surcharge requirements](/platforms/in-person-payments/surcharge#requirements), take into account the following information.

| Requirement                                                   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------- |   |
| **Integration type**                                          | Configuration-based surcharge is supported with:- A [Terminal API integration](/point-of-sale/design-your-integration/) with payment terminals or with a [Tap to Pay](/point-of-sale/ipp-mobile/) Mobile solution.
- A [standalone solution](/point-of-sale/standalone).When using payment terminals, note the required terminal software version:- **v1.108** to apply a maximum surcharge amount per transaction.
- **v1.112** to differentiate between commercial and consumer cards.
- **v1.115** to exclude gratuities (tips) from surcharging.
- **v1.117** to apply surcharges to Mail Order/Telephone Order (MOTO) and Manual Key Entry (MKE) payments. |
| **[API credentials](/development-resources/api-credentials)** | You must have an API credential with an API key and the following [roles](/development-resources/api-credentials#api-permissions):- Management API—Terminal settings read
- Management API—Terminal settings read and writeIf you have a Terminal API integration with [cloud-based communications](/point-of-sale/design-your-integration/choose-your-architecture#cloud-communications), you can use the existing API key that you use for Terminal API requests.                                                                                                                                                                                             |
| **[Webhooks](/development-resources/webhooks)**               | It is recommended to subscribe to **Standard** webhooks and [enable](/platforms/in-person-payments/surcharge#surcharge-in-authorisation-webhooks) receiving the surcharge amount in AUTHORISATION webhook messages.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **Hardware**                                                  | Configuration-based surcharge is not supported with **SFO1** terminals or with [NYC1 card readers](/point-of-sale/ipp-mobile/) (in a Mobile solution).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| **Limitations**                                               | Note the following:- For surcharges on Tap to Pay transactions, the [surcharge confirmation screen](/platforms/in-person-payments/surcharge#surcharge-confirmation-screen) does not show.
- Requests to live Management API endpoints related to terminal settings are subject to [rate limits](/point-of-sale/automating-terminal-management#rate-limits-in-the-live-environment).                                                                                                                                                                                                                                                                             |
| **Setup steps**                                               | For surcharges on Tap to Pay transactions, ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable single tap.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

## How it works

After the surcharge amounts and/or percentages are [configured](#configure-surcharges):

1. You make a payment request like you normally do. There are no special parameters required to trigger the surcharge.

2. The payment terminal or mobile device shows a screen with the purchase amount and instructs your user's customer to present their card.

3. Based on the card that the customer presents, the terminal or Mobile SDK calculates the surcharge using the surcharge amounts and/or percentages you configured.

4. Depending on your configuration and solution, the [surcharge confirmation screen](/platforms/in-person-payments/surcharge#surcharge-confirmation-screen) appears. This enables your user's customer to accept the surcharge, or cancel the transaction.

   In a Mobile solution or if you choose to skip the confirmation screen, you must provide another form of disclosure.

5. If your user's customer accepts the surcharge, the payment is processed and the payment response shows the surcharge amount in the `TotalFeesAmount` field.

## Configure surcharges

The payment acceptance fee charged to your user depends on the payment method brand (scheme), funding source (credit or debit), currency, and the country/region that issued the payment method (domestic or international). Therefore, the surcharge that your user passes on to the customer must be specific for the combination of brand, funding source, currency, and country/region.

The surcharge can be a fixed amount for each transaction, a percentage of the sum of the purchase amount and the tip, or both a fixed amount and a percentage. You can configure the surcharge logic for payments based on the agreements you have with your users.

In addition, you can:

* Specify a maximum surcharge amount.
* Indicate if the surcharge should only be applied if the payment method is a commercial/business card. This is important in countries/regions where surcharges on consumer cards are not allowed.
* Indicate if the surcharge should not be applied to gratuities (tips). This is important in countries/regions where it is prohibited to apply charges to tips.
* Indicate if the surcharge confirmation screen should be shown. If you hide this screen, regulations require you to provide another form of surcharge disclosure.

To configure surcharges:

1. Check the current surcharge configuration (if any) by making a GET request to the `/terminalSettings` endpoint for the [company account](https://docs.adyen.com/api-explorer/Management/latest/get/companies/\(companyId\)/terminalSettings), [merchant account](https://docs.adyen.com/api-explorer/Management/latest/get/merchants/\(merchantId\)/terminalSettings), [store](https://docs.adyen.com/api-explorer/Management/latest/get/stores/\(storeId\)/terminalSettings) or [terminal](https://docs.adyen.com/api-explorer/Management/latest/get/terminals/\(terminalId\)/terminalSettings), and checking the `surcharge` object.

2. Create an overview of all surcharges that you want to apply. For example:

   | Brand      | Only commercial cards | Funding source  | Country/ region | Currency | Percentage | Amount   | Max. amount |
   | ---------- | --------------------- | --------------- | --------------- | -------- | ---------- | -------- | ----------- |
   | eftpos     | false                 | Debit           |                 | AUD      | (none)     | AUD 0.10 | (none)      |
   | Mastercard | false                 | Credit          |                 | AUD      | 0.58 %     | AUD 1    | (none)      |
   | Mastercard | false                 | Debit           |                 | AUD      | 0.58 %     | (none)   | AUD 10      |
   | Visa       | false                 | Credit or Debit | AU, NZ          | AUD      | 0.63 %     | (none)   | (none)      |
   | Visa       | false                 | Credit or Debit |                 | AUD      | 1.63 %     | (none)   | (none)      |
   | Visa       | true                  | Credit or Debit | NL              | EUR      | 1.63 %     | (none)   | (none)      |

   Specifying a country/region applies the surcharge settings only to payment methods issued in that country/region. If not specified, the surcharge applies to all payment methods that meet the rest of the conditions.

3. Make a PATCH request to the `/terminalSettings` endpoint for the [company account](https://docs.adyen.com/api-explorer/Management/latest/get/companies/\(companyId\)/terminalSettings), [merchant account](https://docs.adyen.com/api-explorer/Management/latest/get/merchants/\(merchantId\)/terminalSettings), [store](https://docs.adyen.com/api-explorer/Management/latest/get/stores/\(storeId\)/terminalSettings) or [terminal](https://docs.adyen.com/api-explorer/Management/latest/get/terminals/\(terminalId\)/terminalSettings).\
   In the request body, specify a [surcharge](https://docs.adyen.com/api-explorer/Management/latest/patch/companies/\(companyId\)/terminalSettings#request-surcharge) object with the following properties:

   | Parameter                                                                                                                                                                           | Data type      | Description                                                                                                                                                                                                                                                                                                                                |
   | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
   | [askConfirmation](https://docs.adyen.com/api-explorer/Management/latest/patch/companies/\(companyId\)/terminalSettings#request-surcharge-askConfirmation)                           | Boolean        | Indicates whether to show (**true**) or hide (**false**) the [surcharge confirmation screen](#how-it-works) on the payment terminal.                                                                                                                                                                                                       |
   | [excludeGratuityFromSurcharge](https://docs.adyen.com/api-explorer/Management/latest/patch/companies/\(companyId\)/terminalSettings#request-surcharge-excludeGratuityFromSurcharge) | Boolean        | Indicates whether to apply surcharges only to the purchase amount (**true**) or to the total of purchase amount and tip amount (**false**). Set this parameter to **true** if your country/region prohibits deducting charges from the tips that customers leave for the employees.                                                        |
   | [configurations](https://docs.adyen.com/api-explorer/Management/latest/patch/companies/\(companyId\)/terminalSettings#request-surcharge-configurations)                             | Array\[Object] | Array of payment methods for which to apply surcharges. Each payment method is an array item that includes details about how to apply the surcharge.The order of array items inside the `configurations` array impacts the order of execution. The condition that is met first is executed without checking the rest of the configuration. |

   For each array item in the [configurations](https://docs.adyen.com/api-explorer/Management/latest/patch/companies/\(companyId\)/terminalSettings#request-surcharge-configurations) object, specify:

   | Parameter    | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
   | ------------ | ------------------------------------------------------------------------------------------- |   |
   | `brand`      | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | A payment method [supported for Management API](/development-resources/paymentmethodvariant#management-api), for example `eftpos_australia` or `mc`.                                                                                                                                                                                                                                                                                                                                                                                                       |
   | `currencies` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `currencyCode`: (required) the three-character [ISO currency code](/development-resources/currency-codes).
   - `percentage`: surcharge percentage per transaction up to two decimal places. For example, 1% or 2.27%.
   - `amount`: surcharge amount per transaction, in [minor units](/development-resources/currency-codes).
   - `maxAmount`: the maximum surcharge amount per transaction, in [minor units](/development-resources/currency-codes). This object must contain the `currencyCode` and a `percentage` or an `amount` (or both). |
   | `sources`    |                                                                                             | Can be: **Credit** or **Debit**. If not specified, the `currencies` settings apply to all possible funding sources for the `brand`.                                                                                                                                                                                                                                                                                                                                                                                                                        |
   | `country`    |                                                                                             | The country/region of the issuer, in [two-letter ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code format. If used, the surcharge settings only apply if the payment method was issued in that country/region.                                                                                                                                                                                                                                                                                                            |
   | `commercial` |                                                                                             | Set to **true** to indicate that the surcharge should be applied only in case of a commercial/business card. If not specified, the default value **false** is used. This setting is important in countries/regions where a surcharge is not allowed for consumer cards.This check is not supported on mobile devices used in a Mobile solution. On payment terminals this check is not supported when the internet connection is down.                                                                                                                     |

   **Configure surcharges**

   ```bash
   curl https://management-test.adyen.com/v3/stores/{storeId}/terminalSettings \
   -H 'x-API-key: YOUR_X-API-KEY' \
   -X PATCH \
   -d '{
       "surcharge":{
           "askConfirmation":true,
           "excludeGratuityFromSurcharge":false,
           "configurations":[
               {
                   "brand":"mc",
                   "sources":[
                       "Credit"
                   ],
                   "currencies":[
                       {
                           "currencyCode":"AUD",
                           "percentage":"0.58",
                           "amount":"100"
                       }
                   ]
               },
               {
                   "brand":"mc",
                   "sources":[
                       "Debit"
                   ],
                   "currencies":[
                       {
                           "currencyCode":"AUD",
                           "percentage":"0.58",
                           "maxAmount":"10000"
                       }
                   ]
               },
               {
                   "brand":"eftpos",
                   "sources":[
                      "Debit"
                   ],
                   "currencies":[
                       {
                           "currencyCode":"AUD",
                           "amount":"10"
                       }
                   ]
               },
               {
                   "brand":"visa",
                   "sources":[
                       "Credit",
                       "Debit"
                   ],
                   "currencies":[
                       {
                           "currencyCode":"AUD",
                           "percentage":"0.63"
                       }
                   ],
                   "country":[
                       "AU", "NZ"
                   ]
               },
               {
                   "brand":"visa",
                   "sources":[
                       "Credit",
                       "Debit"
                   ],
                   "currencies":[
                       {
                           "currencyCode":"AUD",
                           "percentage":"1.63"
                       }
                   ]
               },
               {
                   "brand":"visa",
                   "sources":[
                       "Credit",
                       "Debit"
                   ],
                   "currencies":[
                       {
                           "currencyCode":"EUR",
                           "percentage":"1.63"
                       }
                   ],
                   "country":[
                       "NL"
                   ],
                   "commercial":true
               }
           ]
       }
   }'
   ```

   The response returns the surcharge settings as well as all other terminal settings at the level where you made the request.

4. (Optional) Ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to configure **single tap**. When this feature is enabled, the customer doesn't need to present their contactless card again after the terminal has calculated the total amount.

   When accepting payments with surcharges using Tap to Pay on a mobile device, only the single tap flow is available. Ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to configure **single tap**.

## Book the surcharge to your user

To ensure the automatically calculated surcharge is booked to your user's balance account

1. When you [gather the split instructions for the payment](/platforms/in-person-payments/split-transactions/split-payments-at-authorization#gather-data), add a split item for the surcharge:

   * Increase the `split.nrOfItems` by one, to accommodate the surcharge split item you are adding.

   * In the split item for the surcharge, specify:

     | Key                                   | Description                                                                                                                                                                           |
     | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `split.item[ITEM_NUMBER].type`        | The type of split. Set this to **Surcharge**.                                                                                                                                         |
     | `split.item[ITEM_NUMBER].account`     | The account that will receive the surcharge. This is the `balanceAccountID` of one of your user's balance accounts. You cannot split the surcharge between multiple balance accounts. |
     | `split.item[ITEM_NUMBER].reference`   | Your reference for the surcharge, reflected in the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report).                              |
     | `split.item[ITEM_NUMBER].description` | Your description of the surcharge, reflected in the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report).                             |

   Because the surcharge amount is only calculated after the customer presents their card, you do not need to include a surcharge amount in the `split.totalAmount` field or add a `split.item[ITEM_NUMBER].amount` field for the surcharge.

2. Format the split data in one of the following ways:

   * **Option 1**: as a string of form-encoded key-value pairs (using **&** as a separator).
   * **Option 2**: as a JSON object converted to a Base64-encoded string.

   As an example, we use a payment of USD 626.00 that is split into:

   * USD 600.00 to be booked to your user's first balance account as the sale amount.
   * USD 20.00 to be booked to your liable account as your platform's commission.
   * The payment fee to be booked to your user's first balance account. This will be deducted from the sale amount.
   * USD 6.00 to be booked to your user's first balance account as the surcharge.

   In this case, the `split.nrOfItems` is **4** and the `split.totalAmount` is **62000** because the amounts for the payment fee and the surcharge are not known when sending the request.

   ### Tab: Key-value pairs

   1. Turn the split data you gathered into key-value pairs.

      **Split surcharge data as key-value pairs**

      ```raw
      split.api=1
      split.nrOfItems=4
      split.totalAmount=62000
      split.currencyCode=USD
      split.item1.amount=60000
      split.item1.type=BalanceAccount
      split.item1.account=BA00000000000000000000001
      split.item1.reference=Your reference for the sale
      split.item1.description=Your description for the sale
      split.item2.amount=2000
      split.item2.type=Commission
      split.item2.reference=Your reference for your commission
      split.item2.description=Your description for your commission
      split.item3.type=PaymentFee
      split.item3.account=BA00000000000000000000001
      split.item3.reference=Your reference for the fees
      split.item3.description=Your description for the fees
      split.item4.type=Surcharge
      split.item4.account=BA00000000000000000000001
      split.item4.reference=Your reference for the surcharge
      split.item4.description=Your description for the surcharge
      ```

   2. Concatenate the key-value pairs into a string by separating them with ampersands (**&**).

      **Concatenated key-value pairs**

      ```bash
      split.api=1&split.nrOfItems=4&split.totalAmount=62000&split.currencyCode=USD&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=Your reference for the sale&split.item1.description=Your description for the sale&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=Your reference for your commission&split.item2.description=Your description for your commission&split.item3.type=PaymentFee&split.item3.account=BA00000000000000000000001&split.item3.reference=Your reference for the fees&split.item3.description=Your description for the fees&split.item4.type=Surcharge&split.item4.account=BA00000000000000000000001&split.item4.reference=Your reference for the surcharge&split.item4.description=Your description for the surcharge
      ```

   ### Tab: Base64-encoded JSON

   1. Create a JSON object consisting of an `additionalData` object containing the split data you gathered.

      **JSON object**

      ```json
      {
         "additionalData": {
             "split.api": "1",
             "split.nrOfItems": "4",
             "split.totalAmount": "62000",
             "split.currencyCode": "USD",
             "split.item1.amount": "60000",
             "split.item1.type": "BalanceAccount",
             "split.item1.account": "BA00000000000000000000001",
             "split.item1.reference": "Your reference for the sale",
             "split.item1.description": "Your description for the sale",
             "split.item2.amount": "2000",
             "split.item2.type": "Commission",
             "split.item2.reference": "Your reference for your commission",
             "split.item2.description": "Your description for your commission",
             "split.item3.type": "PaymentFee",
             "split.item3.account": "BA00000000000000000000001",
             "split.item3.reference": "Your reference for the fees",
             "split.item3.description": "Your description for the fees",
             "split.item4.type": "Surcharge",
             "split.item4.account": "BA00000000000000000000001",
             "split.item4.reference": "Your reference for the surcharge",
             "split.item4.description": "Your description for the surcharge"
         }
      }
      ```

   2. Encode the JSON object to Base64.

      **Base64 string**

      ```bash
       
      ```

3. [Make a Terminal API payment request](/platforms/in-person-payments/split-transactions/split-payments-at-authorization#split-payment), passing the formatted string of split instructions in the `SaleToAcquirerData` field of the [PaymentRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment) object.

   **Payment with surcharge split instructions as key-value pairs**

   ```json
   {
       "SaleToPOIRequest": {
           "MessageHeader": {
               "ProtocolVersion": "3.0",
               "MessageClass": "Service",
               "MessageCategory": "Payment",
               "MessageType": "Request",
               "SaleID": "POSSystemID12345",
               "ServiceID": "0207111104",
               "POIID": "V400m-324688179"
           },
           "PaymentRequest": {
               "SaleData": {
                   "SaleTransactionID": {
                       "TransactionID": "27908",
                       "TimeStamp": "2022-10-28T10:11:04+00:00"
                   },
                   "SaleToAcquirerData": "split.api=1&split.nrOfItems=4&split.totalAmount=62000&split.currencyCode=USD&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=Your reference for the sale&split.item1.description=Your description for the sale&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=Your reference for your commission&split.item2.description=Your description for your commission&split.item3.type=PaymentFee&split.item3.account=BA00000000000000000000001&split.item3.reference=Your reference for the fees&split.item3.description=Your description for the fees&split.item4.type=Surcharge&split.item4.account=BA00000000000000000000001&split.item4.reference=Your reference for the surcharge&split.item4.description=Your description for the surcharge"
               },
               "PaymentTransaction": {
                   "AmountsReq": {
                       "Currency": "USD",
                       "RequestedAmount": 620.00
                   }
               }
           }
       }
   }
   ```

4. In the [PaymentResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#responses-200) note the following:

   * `POIData.POITransactionID.TransactionID`: The [transaction identifier](/point-of-sale/design-your-integration/terminal-api#transaction-identifier) in the format *tenderReference.pspReference*. Use the PSP reference to keep track of the payment.

   * `PaymentResult.AmountsResp`:

     * `TotalFeesAmount`: The surcharge amount.
     * `AuthorizedAmount`: The total authorized amount, consisting of the original amount plus the surcharge amount.

   * `Response.AdditionalResponse`:

     * `posAuthAmountValue`: The total authorized amount in [minor units](/development-resources/currency-codes).

     * `surchargeAmount`: The surcharge amount in minor units.

   **Response**

   ```json
   {
      "SaleToPOIResponse":{
         "MessageHeader":{},
         "PaymentResponse":{
            "POIData":{
               "POIReconciliationID":"1000",
               "POITransactionID":{
                  "TimeStamp":"2023-04-12T10:49:53.949Z",
                  "TransactionID":"qwiT001681296593002.RJTPF68B2HXXGN82"
               }
            },
            "PaymentReceipt":[...],
            "PaymentResult":{
               "AmountsResp":{
                  "AuthorizedAmount":626.00,
                  "Currency":"USD"
               },
               ...
               "PaymentInstrumentData":{...}
            },
            "Response":{
               "AdditionalResponse":"....posAuthAmountCurrency=USD&posAuthAmountValue=62600&posOriginalAmountValue=62000...",

               "Result":"Success"
            },
            "SaleData":{
               "SaleTransactionID":{
                  "TimeStamp":"2023-04-12T10:49:53.996Z",
                  "TransactionID":"499"
               }
            }
         }
      }
   }
   ```

## Opting out for MOTO and MKE

With terminal software version **v1.117** and later, the surcharge configuration that you set up also applies to [Mail Order/Telephone Order](/point-of-sale/mail-and-telephone-order-moto) (MOTO) and [Manual Key Entry](/point-of-sale/enter-payment-manually) (MKE) payments.

If you have previously developed your own solution for surcharging MOTO and MKE payments, there is a risk of double surcharging: once through the surcharge configuration, and once through your own solution. To avoid this issue, you can opt out of the Adyen surcharge feature for MOTO and MKE payments. You can set this on any level: company account, merchant account, store, or individual payment terminals.

Reach out to your Adyen account manager or technical contact if you want to opt out.

## See also

* [Surcharge compliance guide](/development-resources/surcharge-compliance)
* [Dynamic surcharge](/platforms/in-person-payments/surcharge/dynamic)
* [Card application selection](/point-of-sale/aid-selection-rules)
* [Use API calls to configure terminals](/point-of-sale/automating-terminal-management/configure-terminals-api)
