Tipping on the receipt

Tipping on the receipt is a payment flow where the customer first presents their card and provides a PIN or signature, and then writes a tip amount on the receipt and signs for it. This means that initially the transaction amount is authorised, but the tip amount is not. This is also referred to as overcapture.

To accept tipping in this way and get the full amount settled to your account, you need to implement pre-authorisation:

• Make a pre-authorisation request.
• If the tip is a significant increase of the original amount, adjust the authorisation by increasing the authorised amount with the tip amount.
• Manually capture payment of the final amount.

Our Support Team can configure your account to capture payments with an amount higher than the original amount without adjusting the authorisation. However, this increases the risk of chargebacks (see the conditions).

Before you begin

To implement tipping on the receipt, you need to:

• Build a Terminal API integration.
• Implement the pre-authorisation process.
• Set up standard webhooks and optionally display notifications.

Keep your staff informed with display notifications

While your customer is interacting with the terminal, you may want to show progress messages in your POS app. These can keep your staff informed of the tip amount.

These messages are delivered using display notifications, which are webhooks that are sent to an endpoint that you specify. For information on how to set up and use display notifications, see our display notifications documentation.

Step 1: Pre-authorise the payment

Initiate payment:

1. Make a PaymentRequest , specifying a PaymentRequest body with:

   • SaleData.SaleToAcquirerData: authorisationType=PreAuth to indicate this is a pre-authorisation request.

   For more request and response details, see Pre-authorisation.

2. When you receive the pre-authorisation response:

   • Store the pspReference from the AdditionalResponse for later use when adjusting the authorisation or capturing the payment.

   • If you're using synchronous authorisation adjustment, also URL decode the adjustAuthorisationData blob and store it.

3. Check whether the customer added a tip.

   • If the customer didn't add a tip, proceed to Step 3: Capture the payment.

4. If the customer did add a tip, calculate the tip percentage using the following values from the AdditionalResponse: posadditionalamounts.originalAmountValue and posAmountGratuityValue. These are the original amount and the tip amount in minor units.

   • If the tip is a slight increase of the original amount, proceed to Step 3: Capture the payment.

   • If the tip is a significant increase of the original amount, proceed to Step 2: Adjust the authorisation.
     Though the card schemes have different standards on when to adjust the authorisation, a rule of thumb is to adjust it when the tip amount is higher than 20%.

Step 2 (Optional): Adjust the pre-authorisation

To obtain a new authorisation for the original amount plus the tip amount:

Step 3: Capture the payment

To ensure the original amount plus the tip amount is settled to your account, you need to manually capture the payment:

1. Make a POST request to the  /payments/paymentPspReference/captures  endpoint, specifying:

   • paymentPspReference: The pspReference of the original pre-authorisation.
   • amount: The currency of the final amount and its value in minor units. This is the sum of the pre-authorised amount and the tip.
   • merchantAccount: The name of your merchant account that is used to process the payment.

   For more request and response details, see Pre-authorisation.

2. Make sure you receive the asynchronous standard webhook. This informs you whether the final amount has been captured.

Conditions for tipping with pre-authorisation

In some countries (the US, Singapore, and Hong Kong) a common practice is that the customer signs the tip amount on the receipt after presenting their card and completing the original payment.

To follow this practice, take into account the following:

• Availability: support for authorisation adjustment is limited to specific credit card schemes, and also depends on your Merchant Category Code (MCC).

• Card schemes require an authorisation adjustment if the tip is more than a certain percentage of the original authorised amount. If the issuer declines this additional capture, you can get a chargeback for the portion of the final amount that is above the original amount plus this percentage. The percentage differs per scheme and ranges from 0-20%. If you want to capture amounts higher than the original amount without authorisation adjustment, thereby taking this chargeback risk, contact our Support Team.

• You need to manually capture the payment, ideally before the pre-authorisation expires. Refer to Validity.

• The flow is not supported for wallets and debit cards.

See also