Tipping

Implement tipping (gratuity) in your payment flow.

When a customer includes a tip in their payment, it is booked to your liable account by default. However, you can book the entire tip amount directly to your user's balance account by providing an additional split item in the payment request.

Before you begin

Before you can split a payment that includes a tip, you must:

Read and understand our Terminal API fundamentals.
Configure the method of tipping (POS app or terminal). A tip made on the receipt cannot be booked directly to your user.

Book a payment's tip to your user

When splitting a payment, add a split item for the tip.

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

For the split item of the tip, specify:

Key	Description	Example
`split.item[ITEM_NUMBER].type`	The type of split. Set this to Tip.	split.item3.type=Tip
`split.item[ITEM_NUMBER].account`	Account that will receive the tip. This is the `balanceAccountID` of one of your user's balance accounts. You cannot split the tip between multiple balance accounts.	split.item3.account=BA00000000000000000000001
`split.item[ITEM_NUMBER].reference`	Your reference for the tip, reflected in the Balance Platform Accounting Report.	split.item3.reference=reference_tip
`split.item[ITEM_NUMBER].description`	Your description for the tip, reflected in the Balance Platform Accounting Report.	split.item3.description=description_tip

You do not need to include the tip amount in the split.totalAmount or split.item[ITEM_NUMBER].amount fields, since the tip amount may not be known when creating the payment request.

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

EUR 600.00 to be paid 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 paid to your user's first balance account as the tip.
EUR 20.00 to be paid to your liable account as your platform's commission.

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

Adjust the payment request depending on the configured method of tipping:

When the tip is implemented from the POS app, include an additional AmountsReq.TipAmount object, where you specify the amount of the tip.

In the PaymentResponse note the following:

POIData.POITransactionID.TransactionID: Transaction identifier for the payment.
PaymentResult.AmountsResp:
- TipAmount: amount of the tip. If the customer didn't add a tip, this field is not included.
- AuthorizedAmount: total amount of the payment (original transaction amount plus tip amount).
- 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.