Tipping support in the iOS SDK
This document provides an overview of tipping functionality available when taking card payments through the iOS Payments
SDK.
The usage of tipping is optional. For each call the requestor can specify if tipping should be part of the payment or
not. If tipping is enabled, the payment will return both the total amount and the tipping amount.
Example: Merchant initiates a payment of 150 and tipping is enabled. The card holder decides to give an additional
20 as a tip. The total amount returned from the call would be 170 and the tipping amount would contain 20.
The process to enter tips in the card reader may vary between markets due to differences in tipping behaviour. From an
integration perspective, there is no difference however. The market specific logic is handled by the SDK and the card
reader.
The following prerequisites are required to initiate tipping:
- Tipping is only available on the Zettle card reader.
- Usage of SDK version
1.7.1or later. - The card reader needs to contain the latest software versions.
- Tipping must be enabled for the market connected to the Zettle account used by the merchant. See the list of supported markets for tipping.
Tipping will be made available on a market by market basis. The following markets are supported at the moment:
- United States
- Sweden
- Norway
- Denmark
- Finland
- United Kingdom
- The Netherlands
- France
- Germany
Zettle's tipping function allows customers to add an extra amount to the total sum of their bill (market specific
versions: entering total sum or adding an extra amount), and they can do so straight into your card reader. This
function only works with a Zettle Reader.
Tipping is optional and is enabled per call to the charge-function.
Passing tippingStyle to the
charge(amount:) call does not guarantee that tipping flow will be displayed. This is
because tipping is not supported by all accounts and all card readers.See section prerequisites.
User research showed that the methods to give tips differ between countries. In the UK users want to be prompted with a
question before entering the tip amount. As a contrast in Norway and Sweden, users prefer to enter the total amount
including tip directly.
Starting with SDK version
3.6.0, in the US, UK and some EU markets, users can add a tip based on a percentage of the total amount. You can see the data listed in the following table. |  |  |
|---|---|---|
| Total Amount | Extra Amount | Percentage |
The tipping styles are pre-defined per market and is not configurable.
| Market | Tipping style | Supporting SDK version |
|---|---|---|
| United States | Percentage tipping | 3.6.0 |
| Extra Amount | 3.1.0 | |
| United Kingdom | Percentage tipping | 3.6.0 |
| Extra Amount | 1.7.1 | |
| Sweden | Percentage tipping | 3.6.0 |
| Total Amount | 1.7.1 | |
| Norway | Percentage tipping | 3.6.0 |
| Total Amount | 1.7.1 | |
| Denmark | Percentage tipping | 3.6.0 |
| Extra Amount | 1.7.1 | |
| Finland | Percentage tipping | 3.6.0 |
| Total Amount | 1.7.1 | |
| France | Percentage tipping | 3.6.0 |
| Extra Amount | 3.2.2 | |
| The Netherlands | Percentage tipping | 3.6.0 |
| Total Amount | 1.7.1 | |
| Germany | Percentage tipping | 3.6.0 |
| Total Amount | 1.7.1 |
There is a maximum level validation to prevent accidental or invalid entering of amounts. This can happen for example if
customers enter their PIN code instead of a tip amount. The maximum limit for Europe is 50%, and 100% for the US. If
this level is exceeded, the card reader will display a “Too high amount” warning message.
In markets where the tipping style is
Total amount, there card holder is required to enter the amount to be charged
including tips. If the user enters an amount that is less than the amount entered by the merchant, the card reader will
show a “too low amount” warning message.Yes, tipping requires a minimum version of the card reader software. It’s highly recommended that merchants upgrade the
card reader software prior to accepting payments with tips. The update will take a few minutes to be completed.
The SDK will verify that the correct software is installed on the Zettle card reader when requesting tips. If the card
reader software doesn’t support tipping, a message will be displayed asking the merchant to update the card reader
software.
Important
- Make sure that the card reader and your smartphone or tablet are charged before you update the software.
- Keep the smartphone or tablet close to the card reader during the update.
What happens if a tipping call is made using a Zettle account in a market that doesn’t support tipping?
The payment function will work as before when the tipping flow is not initiated in the card reader.
Tipping is planned be introduced in more markets. Information about the availability will be announced on Github and via
email.