Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Tipping on the receipt

Implement tipping on the receipt in combination with pre-authorisation.

Only when necessary

Tipping on the receipt is harder to implement and subject to conditions. Only implement this if it's absolutely required in your situation.

See Tipping for alternatives.

Here we describe how to implement tipping in your 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.

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 adds more than 20% to the original amount, adjust the authorisation by increasing the authorised amount with the tip amount.
  • Capture payment of the final amount.

Note that tipping in this way is subject to conditions.

Adjusting a pre-authorised amount is supported for American Express, Discover, Mastercard, and Visa credit cards only.

Before you begin

Before you implement tipping, make sure you have:

Keep your staff informed with webhooks

While your shopper is interacting with the terminal, you may want to present progress messages on your cash register. 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, refer to our display notifications documentation.

Step 1: Pre-authorise the payment

Initiate payment:

  1. Make a POST request to a Terminal API endpoint, specifying a PaymentRequest body with:

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

    For more request and response details, refer to 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.

  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.

Step 2 (Optional): Adjust the pre-authorisation

If the tip adds more than 20% to the original amount, increase the authorised amount:

  1. Make a POST request to the /adjustAuthorisation endpoint, specifying:

    • originalReference: The pspReference of the pre-authorisation request.
    • modificationAmount: The currency and value of the new amount in minor units. This is the sum of the pre-authorised amount and the additional amount.
    • additionalData: Depends on whether you use asynchronous or synchronous adjustment.

      Asynchronous adjustment:

      • industryUsage: DelayedCharge

      Synchronous adjustment:

      • adjustAuthorisationData: The adjustAuthorisationData blob you received in the response to your pre-authorisation request, in URL-decoded format.
    • merchantAccount: The name of your merchant account that is used to process the payment.

    For more request and response details, refer to Pre-authorisation.

  2. If you use synchronous authorisation adjustment, URL-decode and store the adjustAuthorisationData blob you receive in the /adjustAuthorisation response. You will need this if you later adjust the authorisation again (although with tipping it is not expected you'll need to adjust the authorisation more than once).

  3. If you use asynchronous authorisation adjustment, make sure you receive the asynchronous notification. This informs you whether the new amount has been authorised.

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 /capture endpoint, specifying:

    • originalReference: The pspReference of the original pre-authorisation.
    • modificationAmount: The currency and value of the final amount 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, refer to Pre-authorisation.

  2. Make sure you receive the asynchronous notification. 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. If you want to follow this practice, take into account that:

  • Tipping with pre-authorisation is allowed in the following industries:

    MCC Description
    4121 Taxicabs and Limousines
    5812 Eating Places and Restaurants
    5813 Drinking Places - Bars, Taverns, Nightclubs, Cocktail Lounges, and Discotheques
    5814 Fast Food Restaurants
    7230 Beauty and Barber Shops
    7298 Health and Beauty Spas
  • Card schemes require an authorisation adjustment if the tip is more than 20% of the original authorised amount. If the issuer declines this additional authorisation, you can get a chargeback for the portion of the final amount that is above the original amount plus 20%.
  • You need to manually capture the payment.
  • The flow is only supported for American Express, Discover, Mastercard, and Visa credit cards. It's not supported for wallets and debit cards.

See also