Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Tipping on the receipt

Implement overcapture: 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.

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 POS 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).

Tipping on the receipt is subject to conditions.

Before you begin

To implement tipping on the receipt, you need to:

Keep your staff informed with display notifications

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 PaymentRequest , specifying a PaymentRequest body with:

    • SaleData.SaleToAcquirerData: authorisationType=PreAuth to indicate 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.

    • 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:

  1. Make a POST request to the /payments/{paymentPspReference}/amountUpdates endpoint, specifying:

    • paymentPspReference: The pspReference of the pre-authorisation request.
    • amount: The currency and value of the new total amount in minor units. This is the sum of the pre-authorised amount and the additional amount.
    • reason: DelayedCharge
    • 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 standard notification. This informs you whether the new amount has been authorised.
  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 total amount in minor units. This is the sum of the pre-authorised amount and the additional amount.
    • additionalData.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. 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).

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 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 standard 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.

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 POS 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