Set Tip Settings

An overview of the Set Tip Settings request message for Android.

• Overview
• Set Tip Settings request
• Set Tip Settings response
• Key to card terminal product categories
• Get Support

Overview

👉 The Set Tip Settings request is used to configure and apply changes to the tipping settings of the ‘Viva.com Terminal’ application, i.e. to enable or disable the tipping feature and to choose which tip options are offered.

The client app must implement a mechanism to send messages using Android intents and URI calls and to receive the result in a custom URI callback.

• Set Tip Settings request originating from the client app to change the tip settings.
• Set Tip Settings response originating from the ‘Viva.com Terminal’ application to return the result of a Set Tip Settings request.

Set Tip Settings request

For a typical Set Tip Settings request, the client app must provide the following information:

Field	Description	Example	Required	Card terminal support	Type
scheme	The Viva's custom URL scheme, the host and the version.	'vivapayclient://pay/v1'	✅
appId	The client app ID. For successful validation, should not be empty.	'com.example.myapp'	✅
action	Set tip settings. For successful validation, should not be empty.	'set_tip_settings'	✅
enableTip	A flag indicating whether the whole tipping feature is enabled. ⚠️This parameter has the highest hierarchy. If it is set to false, the values of all the other tip parameters are ignored.	true	✅		boolean
enableCustomTip	A flag indicating whether the option to manually enter the tip amount is enabled. The default value is false. This parameter is forced to false if enableRoundTip is true.	true			boolean
enablePercentageTip	A flag indicating whether the tip options calculated as percentages of the charge amount are enabled. The default value is false. This parameter is forced to false if enableRoundTip is true.	true			boolean
enableRoundTip	A flag indicating whether the tip option that rounds the tip amount, based on a part of the charge amount, is enabled. The default value is false. ⚠️This option is incompatible with enableCustomTip and enablePercentageTip. If it is set to true, both of them are forced to false.	false			boolean
callback	The URI callback that will handle the result. For successful validation, should not be empty.	'mycallbackscheme://result'	✅

The table below summarises the settings that are applied for each combination:

The above information elements must create a URI call, i.e.

String reqStr = "vivapayclient://pay/v1"
    + "?appId=com.example.myapp"
    + "&action=set_tip_settings"
    + "&enableTip=true"
    + "&enableCustomTip=true"
    + "&enablePercentageTip=false"
    + "&enableRoundTip=false"
    + "&callback=mycallbackscheme://result";

Intent payIntent = new Intent(Intent.ACTION_VIEW, Uri.parse(reqStr));
payIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
payIntent.addFlags(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
startActivity(payIntent);

Set Tip Settings response

After executing the Set Tip Settings request, the ‘Viva.com Terminal’ application responds with a response to indicate if the tip settings have been applied successfully or not.

The result is received as a URI in the callback activity intent:

Uri result = getIntent().getData();

The table below summarises the contents of an approved response.

Field	Description	Example	Card terminal support
callback	The URI callback that will handle the result.	'mycallbackscheme://result'
status	The status of the Set Tip Settings request.	'success'
message	A string containing information about the status of the request.	'Tip settings updated'
action	Set tip settings.	'set_tip_settings'

A Set Tip Settings response result for an approved request looks as follows:

It is expected that certain requests will fail for various reasons. A Set Tip Settings response result for a failed request looks as follows:

Key to card terminal product categories

To understand the icons used on the above tables, see the below table.

Product category	Terminal models	Icon
Android Card Terminals	Android Card Terminal Ethernet, Android Card Terminal 4G, Mobile Card Terminal Plus, Mobile Card Terminal.
'Viva.com Terminal' application for Android	Mini Card Reader, Pocket Card Terminal connected via Bluetooth or USB to the 'Viva.com Terminal' application for Android.
Linux Card Terminals	Countertop, IM20, S900, S800, D200.

Get Support

If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!