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 authorized, 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-authorization:

• Make a pre-authorization request.
• If the tip is a significant increase of the original amount, adjust the authorization by increasing the authorized 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 authorization. However, this increases the risk of chargebacks (see the conditions).

Requirements

To implement tipping on the receipt, you need to:

• Build a Terminal API integration.
• Implement the pre-authorization 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-authorize 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-authorization.

2. When you receive the pre-authorization response:

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

   • If you are using synchronous authorization 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 authorization.
     Though the card schemes have different standards on when to adjust the authorization, a rule of thumb is to adjust it when the tip amount is higher than 20%.

Step 2 (Optional): Adjust the pre-authorization

To obtain a new authorization 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, where paymentPspReference is the pspReference of the original pre-authorization. Specify:

   • amount: The currency of the final amount and its value in minor units. This is the sum of the pre-authorized 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-authorization.

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

Conditions for tipping with pre-authorization

In some countries/regions (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 authorization adjustment is limited to specific credit card schemes, and also depends on your Merchant Category Code (MCC).

• Card schemes require an authorization adjustment if the tip is more than a certain percentage of the original authorized 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 authorization adjustment, thereby taking this chargeback risk, contact our Support Team.

• You need to manually capture the payment, ideally before the pre-authorization expires. Refer to Expiration of authorizations.

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

See also