Surcharge

Payment brands, such as card schemes and debit network providers, charge a fee for accepting payments on their payment network, called a payment acceptance fee. As a platform, you must have agreements in place with your users about how the payment acceptance fee is charged for each payment.

Your users can pass on these costs to their customers by adding a surcharge to their payments.

How it works

To apply payment surcharges, you first have to configure the surcharge amounts and/or percentages.

After the surcharges are configured:

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

2. The payment terminal shows the purchase amount and prompts the customer to present their card.

3. Based on the card that the customer presents, the terminal calculates the surcharge using the surcharge logic you configured.

4. The terminal shows a confirmation screen with the total amount of the payment (sum of the purchase amount, tip, and surcharge), the surcharge amount, and the card scheme that the extra fee is charged for.

   

5. The customer selects the Confirm key to accept, and the payment is processed. The payment response shows the surcharge amount in the TotalFeesAmount field.

   If the customer doesn't accept the surcharge and selects the Cancel key, the whole transaction is cancelled.

Skipping the confirmation screen

It takes a bit of time for the customer to review the confirmation screen with the surcharge details. To avoid this delay in the payment flow, you can configure a setting to hide this screen.

The flow will then be:

1. You make a payment request like you normally do.
2. The customer completes the payment.
3. Based on the card that the customer presents, the terminal calculates the surcharge and adds it to the payment amount during the authorization.

Before you begin

To add a surcharge to a payment, you must:

• Have access to the following roles:

  • Management API—Terminal settings read
  • Management API—Terminal settings read and write

• Configure surcharges for your users at the company, merchant, store or terminal level. You can configure the surcharge logic for payments based on the agreements you have with your users.

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 that issued the payment method (domestic or international). Therefore, the surcharge that your user passes on must be specific for the combination of brand, funding source, currency, and country.
The surcharge fee can be a fixed amount for each transaction, a percentage of the sum of the purchase amount and the tip, or both.

Before you begin, to check the current surcharge configuration make a GET request to the /terminalSettings endpoint for the company account, merchant account, store or terminal, and check the surcharge object.

To configure surcharges:

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

   Brand	Funding source	Country	Currency	Percentage	Amount
   eftpos			AUD	(none)	AUD 0.10
   Mastercard	Credit		AUD	1.2 %	AUD 1
   Mastercard	Debit		AUD	0.58 %	(none)
   Visa	Credit or Debit	AU, NZ	AUD	0.63 %	(none)
   Visa	Credit or Debit		AUD	1.63 %	(none)
   American Express	Credit		AUD	1.5 %	AUD 1.2

   Specifying the country field inside the configurations object applies the surcharge settings only to payment methods issued in that country. If not specified, the surcharge applies to all payment methods that meet the rest of the conditions.

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 properties:

   Parameter	Data type	Description
   askConfirmation	Boolean	Indicates whether to show (true) or hide (false) the surcharge confirmation screen on the terminal.
   configurations	Array[Object]	List of payment methods for which to apply surcharges with the details per payment method. The order of different surcharge objects inside the configurations array impacts the order of execution. The condition that is met first is executed without checking the rest of the configuration.

   In the configurations object, specify:

   Parameter	Required	Description
   brand		A payment method supported for Management API, for example eftpos_australia or mc.
   currencies		An object with: currency code: the three-character ISO currency code. percentage: surcharge percentage per transaction up to two decimal places. For example, 1% or 2.27%. amount: surcharge amount per transaction, in minor units.
   sources		Can be: Credit, Debit. If not specified, the currencies settings apply to all possible funding sources for the brand.
   country		The country of issue of the specified payment method. If used, the surcharge settings only apply to the payment method issued in that country.

   The response returns all terminal settings at the level where you made the request.

3. (Optional) Ask our Support Team 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.

Book the surcharge to your user

By default, the surcharge amount on a payment is booked to your liable balance account. However, you can book this amount directly to your user's balance account.

1. When splitting a payment, add a split item for the surcharge.

   When adding a new split item, always include this in the total number of split items specified in the split.nrOfItems field.

2. For the split item of the surcharge, specify:

   Key	Description	Example
   split.item[ITEM_NUMBER].type	The type of split. Set this to Surcharge.	split.item5.type=Surcharge
   split.item[ITEM_NUMBER].account	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.item5.account=BA00000000000000000000001
   split.item[ITEM_NUMBER].reference	Your reference for the surcharge, reflected in the Balance Platform Accounting Report.	split.item5.reference=reference_surcharge
   split.item[ITEM_NUMBER].description	Your description for the surcharge, reflected in the Balance Platform Accounting Report.	split.item5.description=description_surcharge

   You do not need to include the surcharge amount in the split.totalAmount or split.item[ITEM_NUMBER].amount fields, since the surcharge amount is only calculated after the customer presents their card.

For example, a payment of EUR 636.00 is split into:

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

In this case, set the split.nrOfItems to 5 and split.totalAmount to 62000 (the amounts for the tip, payment fee, and surcharge are not known when sending the payment request).

In the PaymentResponse note the following:

• POIData.POITransactionID.TransactionID: Transaction identifier for the payment.

• PaymentResult.AmountsResp:

  • AuthorizedAmount: total amount of the payment (the sum of the original transaction amount, tip amount, and surcharge amount).
  • TipAmount: amount of the tip. If the customer didn't add a tip, this field is not included.

  • Currency: currency of the payment.

    • Response.Result: Success
    • Response.AdditionalResponse: additional transaction data. Depending on the format you used in the request, you receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object. This includes:
      • posadditionalamounts.originalAmountValue: the original transaction amount in minor units.
      • posAmountGratuityValue: the tip amount in minor units.
      • authorisedAmountValue: the total authorised amount in minor units, which includes the surcharge amount.