Tips and surcharges

Introduction

A tip is an extra amount added to a purchase to thank the merchant. E.g. the customer may give a $2 tip to the merchant to thank them for the delicious meal.

A surcharge is an extra amount added to a purchase to cover the fees the merchant pays for the transaction. E.g. the merchant may add a $2 surcharge to cover the credit card fee.

When tips and surcharges are added to a purchase, they increase the total amount of money that is transferred. E.g. a $100 purchase with a $10 tip and a $2 surcharge equals a $112 total amount.

{
    "pos_ref_id": "aa2bc19f-c546-421c-sa82-2294fc25a13e",
    "purchase_amount": 10000,
    "tip_amount": 1000,
    "surcharge_amount": 200,
    "bank_noncash_amount": 11200,
    ...
}

📘

Tips and surcharges should not be added to the transaction amount (e.g. purchaseAmount); they should be kept separate by using the tipAmount and surchargeAmount fields.

POS-based vs terminal-based

Tips and surcharges can either be applied by the POS (POS-based) or applied by the EFTPOS terminal (terminal-based). Here are the differences.

POS-based	Terminal-based
To use the POS-based method, include the tip or surcharge in the request, e.g. surchargeAmount: 200. Likewise, the response will contain surchargeAmount: 200.	To use the terminal-based method, configure settings on the terminal to add a tip or surcharge automatically or enable one to be entered manually. The response will contain surchargeAmount: 200 even though this wasn’t provided in the request.
The POS-based method overrides the terminal-based method, e.g. the terminal applies a $1 surcharge, but the POS requests a $2 surcharge, so instead, the $2 surcharge is applied.	The terminal-based method can be overridden.
The terminal usually processes the transaction as a single line item.	The terminal usually processes the transaction as two line items: one for the purchase and one for the surcharge.

Enable tips and surcharges

Tipping and surcharging can only be used if it is allowed by the EFTPOS terminal's settings.

When using Gecko Bank for testing, you must open the MXA Settings app then ensure the Purchase setting is enabled, then enable both Tipping and Surcharge.

To enable terminal-based surcharging, open the MXA Settings app > ensure the Purchase setting is enabled > enable Surcharge > enter a Terminal surcharge amount.

Tips

POS-based tipping can be used for purchase transactions. To add a tip to a purchase, call the POST /v1/purchase endpoint and include the tipAmount in the request body. For example, the following will add a $10 tip.

{
    "posRefId": "aa2bc19f-c546-421c-sa82-2294fc25a13e",
    "purchaseAmount": 10000,
    "tipAmount": 1000
}

📘

Note:

• For a tip-only transaction, use a purchase transaction with purchaseAmount: 0 but with a tipAmount of a positive number.
• Tipping and cashout cannot be used in the same transaction. To use both, you will need to make two transactions: a purchase with tipping followed by a cashout-only transaction.

Surcharges

POS-based surcharging can be used for purchase, cashout-only, MOTO, and pre-authorisation transactions. To add a surcharge to a purchase, call the POST /v1/purchase endpoint and include the surchargeAmount in the request body. For example, the following will add a $2 surcharge.

{
    "posRefId": "aa2bc19f-c546-421c-sa82-2294fc25a13e",
    "purchaseAmount": 10000,
    "surchargeAmount": 200
}

📘

To prevent adding a surcharge even if terminal-based surcharging is enabled, use surchargeAmount: 0 in the request, as this will override the terminal-based surcharge.

Integrating

Your POS can either handle surcharges manually or automatically. For example, if a merchant has a 2% surcharge on American Express cards, they can do either of the following.

• Manual surcharging — the merchant must enter the amount of the surcharge (2% or $2) into the POS.
• Automatic surcharging — the POS has been configured to charge a 2% surcharge on American Express cards, so it adds the surcharge automatically without the merchant needing to enter the amount.

Automatic surcharging can save time for the merchant; however, it requires more development work.

Testing

When using Gecko Bank for testing, the app will prompt you to accept the surcharge. Click Yes then continue with the transaction as normal.