--- title: "Dynamic surcharge" description: "Provide the surcharge amount in your Terminal API request." url: "https://docs.adyen.com/platforms/in-person-payments/surcharge/dynamic" source_url: "https://docs.adyen.com/platforms/in-person-payments/surcharge/dynamic.md" canonical: "https://docs.adyen.com/platforms/in-person-payments/surcharge/dynamic" last_modified: "2026-05-12T18:42:28+02:00" language: "en" --- # Dynamic surcharge Provide the surcharge amount in your Terminal API request. If you want to be in full control of surcharges, you can specify the surcharge amount in your in-person payment request. We refer to this as dynamic surcharge. To calculate the surcharge amount, you can use a third-party service or create your own calculation logic. If you accept ecommerce as well as point-of-sale payments, you can use the same calculation logic for both sales channels, taking into account all applicable compliance requirements. Depending on your [use case](/platforms/in-person-payments/surcharge#surcharge-methods), you can combine dynamic surcharge with [configuration-based surcharge](/platforms/in-person-payments/surcharge/configuration). ## 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** | Dynamic surcharge is supported with a [Terminal API integration](/point-of-sale/design-your-integration/) with payment terminals on terminal software version **1.118** or later. | | **[API credentials](/development-resources/api-credentials)** | To configure showing the [surcharge confirmation screen](/platforms/in-person-payments/surcharge#surcharge-confirmation-screen), 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. | | **Limitations** | 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** | Before you start:- [Enable receiving the issuer country/region](/point-of-sale/card-acquisition/identifiers) in API responses and webhook messages. - Ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable single tap. | ## How it works To use dynamic surcharge: 1. Design the customer experience. We recommend the following: * To inform customers about the changed amount after the surcharge is calculated, [configure showing](#show-confirmation) the [surcharge confirmation screen](/platforms/in-person-payments/surcharge#surcharge-confirmation-screen). If you hide this screen, regulations require you to provide another form of surcharge disclosure. * Use the single tap flow. This means that for contactless payments, customers do not need to tap again when they confirm they accept the surcharge. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable single tap. 2. To get the details that are needed to calculate the surcharge amount, you [make a card acquisition request](#card-acquisition-request). These details include, for example, the transaction amount and currency, card brand, funding source, and issuing country of the card. Note the following: * In Australia the surcharge compliance requirements are simple enough that you can consider skipping card acquisition. * Also note that Mobile solutions currently do not support card acquisition. 3. On the payment terminal, a payment screen appears and your user's customer taps, inserts, or swipes their card. 4. When you receive the card acquisition response, you pass the details for the surcharge calculation to your own surcharge calculation logic or to the third-party surcharge calculation service. 5. When you get the calculated surcharge amount from your own system or the third party, you [make a payment request with the surcharge amount](#payment-with-surcharge) and the split instructions in the `SaleToAcquirerData`. The payment request must also refer to the card acquisition. 6. The 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 configured to skip this Adyen-provided confirmation screen, you must provide another form of disclosure. 7. If your user's customer accepts the surcharge, the payment is processed and the payment response shows the surcharge amount in the `TotalFeesAmount` field. ## Show the confirmation screen Adyen provides a surcharge confirmation screen that appears on the payment terminal to let the customer review and accept the surcharge, or cancel the transaction. You can configure this screen to be skipped. But if you do, you must provide another form of disclosure. To configure showing or hiding the surcharge confirmation screen: 1. Optionally, check the current setting for the surcharge confirmation screen 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). Check the `surcharge.askConfirmation` parameter. 2. 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 parameter: | 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. | **Show the surcharge confirmation screen** ```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 } }' ``` 3. Note that the response returns the setting for the surcharge confirmation screen as well as all other terminal settings at the level where you made the request. ## 1. Make a card acquisition request To calculate the surcharge amount, you need to know certain details. For example, if the customer is using a credit or debit card, and where the card was issued. We recommend getting these details through a card acquisition request. The response provides the details of the card that the customer presents to the payment terminal. 1. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) card acquisition request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **CardAcquisition**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **CardAcquisition** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (`POIID`) being used. | | `SaleID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [CardAcquisitionRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/cardacquisition) object with: | Parameter | Required | Description | | ---------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `SaleData.SaleTransactionID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `TransactionID`: Your reference to identify a payment. We recommend using a unique value per payment. - `TimeStamp`: The date and time of the request in [UTC format](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `CardAcquisitionTransaction` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `TotalAmount`: The amount due for the goods or services that the customer wants to purchase. | The examples show a card acquisition when the customer wants to purchase USD 620.00 worth of goods or services. **Simple card acquisition request** ```json { "SaleToPOIRequest": "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "CardAcquisition", "MessageType": "Request", "ServiceID": "797", "SaleID": "POSSystemID12345", "POIID": "V400m-324688179" }, "CardAcquisitionRequest": { "SaleData": { "SaleTransactionID": { "TransactionID": "369", "TimeStamp": "2026-01-05T15:57:06.973Z" } }, "CardAcquisitionTransaction": { "TotalAmount": 620.00 } } } } ``` When the card acquisition succeeds, the response contains a `message` of **CARD\_ACQ\_COMPLETED** in the `AdditionalResponse`. **Card acquisition response** ```json { "SaleToPOIResponse": { "CardAcquisitionResponse": { "POIData": { "POIReconciliationID": "1000", "POITransactionID": { "TimeStamp": "2026-01-05T15:57:20.465Z", "TransactionID": "BV0q001767628639000" } }, "PaymentInstrumentData": { "CardData": { "CardCountryCode": "840", "MaskedPan": "600007 **** 7003", "PaymentBrand": "mc", "SensitiveCardData": { "ExpiryDate": "0330" } }, "PaymentInstrumentType": "Card" }, "Response": { "AdditionalResponse": "PaymentAccountReference=t9BVKrTbgJT11Igro8dtfsmUVrLnL&alias=P601291289070502&aliasType=Default&backendGiftcardIndicator=false&cardBin=600007&cardHolderName=S%2Hopper&cardIssuerCountryId=840&cardIssuingBank=Adyen%20TEST&cardScheme=mc&cardSummary=7003&cardType=mc&dcc.dccRefusalReason=Currencies%20are%20the%20same&expiryMonth=03&expiryYear=2030&fundingSource=CREDIT&giftcardIndicator=false&isCardCommercial=false&iso8601TxDate=2026-01-05T15%3a57%3a20.465Z&issuerCountry=US&merchantReference=577&message=CARD_ACQ_COMPLETED&paymentMethod=mc&paymentMethodVariant=mccredit&posAmountCashbackValue=0&posAmountGratuityValue=0&posAuthAmountCurrency=USD&posAuthAmountValue=62000&posEntryMode=ICC&posOriginalAmountValue=62000&posadditionalamounts.originalAmountCurrency=USD&posadditionalamounts.originalAmountValue=62000&shopperCountry=US&store=YOUR_STORE&tid=47069832&transactionType=GOODS_SERVICES&txdate=05-01-2026&txtime=16%3a57%3a20", "Result": "Success" }, "SaleData": { "SaleTransactionID": { "TimeStamp": "2026-01-05T15:57:06.973Z", "TransactionID": "577" } } }, "MessageHeader": { "MessageCategory": "CardAcquisition", "MessageClass": "Service", "MessageType": "Response", "POIID": "V400m-324688179", "ProtocolVersion": "3.0", "SaleID": "POSSystemID12345", "ServiceID": "979" } } } ``` 2. From the [CardAcquisitionResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/cardacquisition#responses-200-Response), get the details that are needed for the surcharge calculation. Also get the `POITransactionID` details, which you will need to specify later in your payment request. | Parameter | Usage | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POIData.POITransactionID` | Keep the `TimeStamp` and `TransactionID`, because you need these card acquisition details in your payment request. | | `PaymentInstrumentData.CardData` | Includes details you may need for the surcharge calculation:- `CardCountryCode`: The three-digit code of the issuer country/region. - `PaymentBrand`: The type of payment card. | | `Response.AdditionalResponse` | Includes details you may need for the surcharge calculation. | As an example, the `AdditionalResponse` from the `CardAcquisitionResponse` above includes the following details that can be useful for the surcharge calculation: | Parameter + value | Description | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `cardIssuerCountryId=840` | The three-digit code of the issuer country/region. | | `cardScheme=mc` | The card scheme. | | `cardType=mc` | The card type. | | `fundingSource=CREDIT` | The funding source used for the transaction, such as a credit, debit, prepaid, or charge card. In other words: where the customer's money comes from. | | `isCardCommercial=false` | Indicates if this is a commercial card or a consumer card. When **true**, it is a commercial card. When **false**, it is a consumer card. | | `issuerCountry=US` | The two-letter code of the issuer country/region. | | `paymentMethod=mc` | The payment method on the brand or scheme level. | | `paymentMethodVariant=mccredit` | The payment method on the product level. | | `posAuthAmountCurrency=USD` | The three-letter code of the transaction currency. | | `posAuthAmountValue=62000` | The transaction amount in minor units. | | `posOriginalAmountValue=62000` | The transaction amount before surcharge, gratuity, adjustments, and such (if any). | | `shopperCountry=US` | The two-letter code of the customer's country/region. | If the `AdditionalResponse` doesn't include the expected details, check if you enabled receiving those details. Refer to [Receive identifiers](/point-of-sale/card-acquisition/identifiers#receiving-identifiers-in-responses). 3. Pass the relevant details to your own surcharge calculation system or to your third-party surcharge calculation service. ## 2. Add a surcharge and book it to your user When you have received the calculated surcharge amount from your own system or the third-party surcharge calculation service, make a Terminal API payment request with the following information in the `SaleToAcquirerData`: * The surcharge amount, specified using the `surchargeFee` field. * Split instructions for the payment, including how to split the surcharge. 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, and add the calculated surcharge fee. * 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). | * Add a `surchargeFee` parameter with the calculated surcharge amount as the value. Note that this parameter is *not* a split parameter, and that you must *not* use minor units for the surcharge amount. 2. Format the split data and surcharge amount 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. The `split.nrOfItems` is **4** and the `split.totalAmount` is **62000** because the amounts for the payment fee and the surcharge should not be added to the original amount. ### Tab: Key-value pairs 1. Turn the split data you gathered and the surcharge amount 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 surchargeFee=6.00 ``` 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&surchargeFee=6.00 ``` ### Tab: Base64-encoded JSON 1. Create a JSON object consisting of an `additionalData` object containing the split data you gathered and the surcharge amount. Note that the surcharge amount must be specified as a string value, not as a numeric value. **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", "surchargeFee": "6.00" } } ``` 2. Encode the JSON object to Base64. **Base64 string** ```bash ewogICAiYWRkaXRpb25hbERhdGEiOiB7CiAgICAgICJzcGxpdC5hcGkiOiAiMSIsCiAgICAgICJzcGxpdC5uck9mSXRlbXMiOiAiNCIsCiAgICAgICJzcGxpdC50b3RhbEFtb3VudCI6ICI2MjAwMCIsCiAgICAgICJzcGxpdC5jdXJyZW5jeUNvZGUiOiAiVVNEIiwKICAgICAgInNwbGl0Lml0ZW0xLmFtb3VudCI6ICI2MDAwMCIsCiAgICAgICJzcGxpdC5pdGVtMS50eXBlIjogIkJhbGFuY2VBY2NvdW50IiwKICAgICAgInNwbGl0Lml0ZW0xLmFjY291bnQiOiAiQkEwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSIsCiAgICAgICJzcGxpdC5pdGVtMS5yZWZlcmVuY2UiOiAiWW91ciByZWZlcmVuY2UgZm9yIHRoZSBzYWxlIiwKICAgICAgInNwbGl0Lml0ZW0xLmRlc2NyaXB0aW9uIjogIllvdXIgZGVzY3JpcHRpb24gZm9yIHRoZSBzYWxlIiwKICAgICAgInNwbGl0Lml0ZW0yLmFtb3VudCI6ICIyMDAwIiwKICAgICAgInNwbGl0Lml0ZW0yLnR5cGUiOiAiQ29tbWlzc2lvbiIsCiAgICAgICJzcGxpdC5pdGVtMi5yZWZlcmVuY2UiOiAiWW91ciByZWZlcmVuY2UgZm9yIHlvdXIgY29tbWlzc2lvbiIsCiAgICAgICJzcGxpdC5pdGVtMi5kZXNjcmlwdGlvbiI6ICJZb3VyIGRlc2NyaXB0aW9uIGZvciB5b3VyIGNvbW1pc3Npb24iLAogICAgICAic3BsaXQuaXRlbTMudHlwZSI6ICJQYXltZW50RmVlIiwKICAgICAgInNwbGl0Lml0ZW0zLmFjY291bnQiOiAiQkEwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSIsCiAgICAgICJzcGxpdC5pdGVtMy5yZWZlcmVuY2UiOiAiWW91ciByZWZlcmVuY2UgZm9yIHRoZSBmZWVzIiwKICAgICAgInNwbGl0Lml0ZW0zLmRlc2NyaXB0aW9uIjogIllvdXIgZGVzY3JpcHRpb24gZm9yIHRoZSBmZWVzIiwKICAgICAgInNwbGl0Lml0ZW00LnR5cGUiOiAiU3VyY2hhcmdlIiwKICAgICAgInNwbGl0Lml0ZW00LmFjY291bnQiOiAiQkEwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMSIsCiAgICAgICJzcGxpdC5pdGVtNC5yZWZlcmVuY2UiOiAiWW91ciByZWZlcmVuY2UgZm9yIHRoZSBzdXJjaGFyZ2UiLAogICAgICAic3BsaXQuaXRlbTQuZGVzY3JpcHRpb24iOiAiWW91ciBkZXNjcmlwdGlvbiBmb3IgdGhlIHN1cmNoYXJnZSIsCiAgICAgICJzdXJjaGFyZ2VGZWUiOiAiNi4wMCIKICAgfQp9 ``` 3. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) payment request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Payment**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Payment** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (`POIID`) being used. | | `SaleID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [PaymentRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment) object with: | Parameter | Required | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SaleData.SaleTransactionID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `TransactionID`: Your reference to identify a payment. We recommend using a unique value per payment. - `TimeStamp`: The date and time of the request in [UTC format](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). | | `SaleData.SaleToAcquirerData` | | The formatted string specifying the surcharge. | | `PaymentTransaction.AmountsReq` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Currency`: The transaction [currency](/development-resources/currency-codes). - `RequestedAmount`: The transaction amount due for the goods or services, without surcharge, gratuity, or any other adjustment. | | `PaymentData.CardAcquisitionReference` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object referring to the card acquisition:- `TimeStamp`: The time stamp returned in the `POIData.POITransactionID` of the card acquisition response. - `TransactionID`: The transaction ID returned in the `POIData.POITransactionID` of the card acquisition response. | **Payment request with surcharge** ```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":"2026-01-05T15:59:49.294Z" }, "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&surchargeFee=6.00" }, "PaymentTransaction":{ "AmountsReq":{ "Currency":"USD", "RequestedAmount":620.00 } }, "PaymentData":{ "CardAcquisitionReference":{ "TimeStamp":"026-01-05T15:57:20.465Z", "TransactionID":"BV0q001767628639000" } } } } } ``` 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, consisting of the original amount plus the surcharge amount. * `surchargeAmount`: The surcharge amount in minor units. **Payment response** ```json { "SaleToPOIResponse": { "MessageHeader": {...}, "PaymentResponse": { "POIData": { "POIReconciliationID": "1000", "POITransactionID": { "TimeStamp": "2026-01-06T11:27:24.575Z", "TransactionID": "BV0q001767698805001.SWF7F9NR99LJCK75" } }, "PaymentReceipt": [...], "PaymentResult": { "AmountsResp": { "AuthorizedAmount": 626, "Currency": "USD", "TotalFeesAmount": 6 }, ... "PaymentInstrumentData": { "CardData": { "CardCountryCode": "840", "EntryMode": [ "ICC" ], "MaskedPan": "600007 **** 7003", "PaymentBrand": "mc", "SensitiveCardData": { "CardSeqNumb": "23", "ExpiryDate": "0330" } }, "PaymentInstrumentType": "Card" } }, "Response": { "AdditionalResponse": "...cardIssuerCountryId=840&cardScheme=mc&ccardType=mc&fundingSource=CREDIT&isCardCommercial=false&issuerCountry=US&paymentMethod=mc&paymentMethodVariant=mccredit...&posAuthAmountCurrency=USD&posAuthAmountValue=62600&posOriginalAmountValue=62000&posadditionalamounts.originalAmountCurrency=USD&posadditionalamounts.originalAmountValue=62000...shopperCountry=US...&surchargeAmount=600...", "Result": "Success" }, "SaleData": {...} } } } } ``` ## See also * [Surcharge compliance guide](/development-resources/surcharge-compliance) * [Configuration-based surcharge](/platforms/in-person-payments/surcharge/configuration) * [Card acquisition](/point-of-sale/card-acquisition) * [Use API calls to configure terminals](/point-of-sale/automating-terminal-management/configure-terminals-api)