Tipping & surcharges

Introduction

A tip is an extra amount added to a purchase to thank the merchant - for example, a $2 tip after a meal.

A surcharge is an extra amount added to a purchase to cover the fees the merchant pays for the transaction — for example, a $2 surcharge to cover the cost of a credit card payment.

When tips and surcharges are added to a purchase, they increase the total amount transferred. For example:

⚠️

Tips and surcharges must not be added into purchase_amount. Always pass them as separate fields - tip_amount and surcharge_amount. Adding them to the purchase amount risks double-charging if terminal-based tipping or surcharging is also active.

POS-based vs terminal-based

Both tips and surcharges can be applied in one of two ways: by the POS, or by the terminal. These approaches are mutually exclusive.

Tipping

Tipping is supported on purchase transactions.

POS-based tipping

Include tip_amount in the purchase request:

POST /v1/transactions

{
  "purchase_details": {
    "purchase_amount": 10000,
    "tip_amount": 1000
  }
}

📘

tip_amount: 0 and omitting tip_amount produce different results. Setting it to 0 skips the tipping screen; omitting it lets the terminal prompt the customer if tipping is enabled.

Terminal-based tipping

Omit tip_amount from the request. The terminal will prompt the customer to enter a tip if tipping is enabled in its settings. The applied tip amount will be returned in result_amounts.tip_amount once the transaction is finalised.

Enabling tipping

Terminal-based tipping requires configuration by the merchant's bank or payment provider. The merchant must contact their payment provider to enable this.

When testing with Gecko Bank, tipping can only be used if it is enabled on the terminal. When testing with Gecko Bank, open the MXA Settings app and enable both the Tipping settings.

Surcharges

Surcharging is supported on purchase, cashout, and MOTO transactions.

POS-based surcharge

Include surcharge_amount in the request:

POST /v1/transactions

{
  "purchase_details": {
    "purchase_amount": 10000,
    "surcharge_amount": 200
  }
}

The total amount presented to the customer at card presentment will be: purchase_amount + surcharge_amount.

Setting surcharge_amount will override any terminal-based surcharge configuration. To explicitly suppress a surcharge even when terminal-based surcharging is enabled, set surcharge_amount: 0.

Terminal-based surcharge

Omit surcharge_amount from the request entirely. The terminal will apply a surcharge automatically based on its bank configuration. The applied amount will be returned in result_amounts.surcharge_amount once the transaction is finalised.

⚠️

"surcharge_amount": 0 and omitting surcharge_amount produce different results. Setting it to 0 explicitly suppresses the surcharge; omitting it allows the terminal to apply one. A common pitfall is sending 0 unintentionally when terminal-based surcharging is enabled, which silently disables it.

POS surcharge integration approaches

When implementing POS-based surcharging, your POS can handle the surcharge calculation either manually or automatically:

• Manual surcharging - the merchant enters the surcharge amount into the POS before each transaction
• Automatic surcharging - the POS is configured with surcharge rules (e.g. 2% on American Express cards) and calculates and applies the surcharge automatically

Automatic surcharging saves time for the merchant but requires more development work.

Enabling surcharges

Terminal-based surcharging requires configuration by the merchant's bank or payment provider. The merchant must contact their payment provider to enable this.

When testing with Gecko Bank, open the MXA Settings app, enable the Surcharge settings, and enter a Terminal surcharge amount. When processing a transaction, Gecko Bank will prompt you to accept the surcharge - click Yes to continue.

Reading the finalised amounts

Regardless of whether POS-based or terminal-based amounts were used, always read the final applied amounts from result_amounts in the finalised transaction response. This is the source of truth for displaying amounts on tax invoices and calculating refunds.

"result_amounts": {
  "purchase_amount": 10000,
  "tip_amount": 1000,
  "surcharge_amount": 200,
  "cashout_amount": 0,
  "refund_amount": 0,
  "moto_amount": 0
}