Skip to main content

Setting tipping per payment from your POS app (local tipping options)

For POS integrators: how to enable and set up tipping for each payment through AppSwitch or the Cloud API, regardless of the merchant's MCC code or Softpay app settings.

Who this is for

This article is for POS integrators whose app starts payments in Softpay through the AppSwitch SDK or the Cloud API. If you are a merchant, or you onboard merchants by email or through the Onboarding API, see Tipping in Softpay instead.

What local tipping options do

Your POS app can send tipping options with each payment. These are called local tipping options. When they are included, they take precedence over everything else:

  • They work even if the merchant's MCC code does not qualify for tipping.

  • They work even if tipping is not enabled for the merchant on Softpay's side.

  • The tipping settings in the Softpay app are ignored for that payment.

This lets a POS provider control tipping for all its merchants from the POS itself, without asking Softpay to enable tipping merchant by merchant.

Requirements

Local tipping options need both of these:

  • In your POS app: AppSwitch SDK 1.6.0 or newer.

  • On the device: Softpay app 2.3.0 or newer. If the merchant uses a white-label version of the Softpay app, its version number will differ. In that case, check that the sdkVersion reported by the connected app is 1.9.14 or newer. You can read it at runtime from client.clientManager.capabilities.descriptor.sdkVersion.

The sdkVersion is the version of the SDK built into the Softpay app. It is not something you install or integrate yourself.

Using the Cloud API? Local tipping options are supported there too. See the Cloud API documentation for the request fields.

Options you can set

In AppSwitch, tipping options are set with the TippingLocalOptions class:

  • variant (required): when and how the tip is entered, for example TIP_BEFORE_TAP, TIP_AFTER_TAP or TOTAL_AFTER_TAP. Check which variants the Softpay app supports with Capabilities.supportedTippingVariants first.

  • percentages (optional): up to 3 preset tip percentages.

  • highTip (optional): the highest tip allowed, as a percentage. The default is 100.

  • employeeReference (optional): the staff member the tip belongs to.

  • tipPrompt (optional): shows a "skip tip" screen before the add-tip screen. This only works with newer versions of the Softpay app. On older versions it is ignored and the payment continues without the skip-tip screen.

When the payment fails

The payment fails if the tipping options are invalid, which happens if:

  • the variant is not supported by the Softpay app

  • there are more than 3 percentages

  • a percentage is negative, higher than highTip or higher than 100, or all percentages are zero

  • highTip is zero, negative or higher than 100

Good to know

  • Tipping never applies to refunds.

  • If your POS never uses tipping, send null rather than TippingOff. This avoids compatibility issues.

  • To use the merchant's own tipping settings from the Softpay app instead, use TippingRemoteOptions.

Further reading

Did this answer your question?