Dynamic surcharge

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, you can combine dynamic surcharge with configuration-based surcharge.

Requirements

In addition to the general surcharge requirements, take into account the following information.

How it works

To use dynamic surcharge:

1. Optionally, you configure to show or hide the surcharge confirmation screen.
   If you hide this screen, regulations require you to provide another form of surcharge disclosure.

2. To get the details that are needed to calculate the surcharge amount, you make a 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 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, merchant account, store or terminal. Check the surcharge.askConfirmation parameter.

2. Make a PATCH request to the /terminalSettings endpoint for the company account, merchant account, store or terminal.
   In the request body, specify a surcharge object with the following parameter:

   Parameter	Data type	Description
   askConfirmation	Boolean	Indicates whether to show (true) or hide (false) the surcharge confirmation screen on the payment terminal.

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 card acquisition request, specifying:

   • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to CardAcquisition.

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		CardAcquisition
     MessageType		Request
     ServiceID		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		Your unique ID for the POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • The CardAcquisitionRequest object with:

     Parameter	Required	Description
     SaleData.SaleTransactionID		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.
     CardAcquisitionTransaction		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.

   When the card acquisition succeeds, the response contains a message of CARD_ACQ_COMPLETED in the AdditionalResponse.

2. From the CardAcquisitionResponse, 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.

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, 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.
     split.item[ITEM_NUMBER].description	Your description of the surcharge, reflected in the 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.

3. Make a Terminal API payment request, specifying:

   • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Service
     MessageCategory		Payment
     MessageType		Request
     ServiceID		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		Your unique ID for the POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • The PaymentRequest object with:

     Parameter	Required	Description
     SaleData.SaleTransactionID		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.
     SaleData.SaleToAcquirerData		The formatted string specifying the surcharge.
     PaymentTransaction.AmountsReq		An object with: Currency: The transaction currency. RequestedAmount: The transaction amount due for the goods or services, without surcharge, gratuity, or any other adjustment.
     PaymentData.CardAcquisitionReference		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.

4. In the PaymentResponse note the following:

   • POIData.POITransactionID.TransactionID: The 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.

See also