Set Online request

An overview of the Set Online request message for Android.

• Overview
• Set Online request
• Set Online response
• Notes
• Key to card terminal product categories
• Get Support

Overview

👉 The Set Online request is used to trigger the ‘Viva.com Terminal’ application to attempt switching from Store and Forward (SAF/offline) mode to online mode.

The Set Online request can be used when the terminal is operating in offline(SAF) mode and the integrator wants to force the application to try going back online and upload any stored offline transactions.

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 Online request originating from the client app to trigger the ‘Viva.com Terminal’ application to attempt switching from SAF mode to online mode.
• Set Online response originating from the ‘Viva.com Terminal’ application to return the result of the Set Online request.

Set Online request

Using the setOnline action, the client app can trigger the ‘Viva.com Terminal’ application to attempt exiting SAF mode and return the result through the provided callback URI.

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

Field	Description	Example	Required	Card terminal support
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	The action to be executed. For Set Online, the value must be setOnline.	'setOnline'	✅
callback	The URI callback that will handle the result. For successful validation, should not be empty.	'mycallbackscheme://result'	✅

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

Intent payIntent = new Intent(Intent.ACTION_VIEW, Uri.parse("vivapayclient://pay/v1"
        + "?appId=com.example.myapp"
        + "&action=setOnline"
        + "&callback=mycallbackscheme://result"));

payIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
payIntent.addFlags(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
startActivity(payIntent);

Set Online response

After executing a Set Online request, the ‘Viva.com Terminal’ application responds with a result indicating whether the attempt to switch back online was successful.

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

Uri result = getIntent().getData();

The table below summarizes the contents of a response.

Field	Description	Example	Card terminal support
callback	The URI callback that will handle the result.	'mycallbackscheme://result'
status	The status of the request. Possible values are success and fail.	'success'
message	A string containing information about the request status.	'Set online completed'
action	Set Online action.	'setOnline'
setOnlineResult	The result of the SAF exit attempt. Possible values are Success and Failed.	'Success'

A successful Set Online response result looks as follows:

A failed Set Online response result looks as follows:

Notes

• The request does not require any Set Online-specific input fields beyond the standard InterApp request fields.
• status=success means that the terminal is online after the request is handled. This can also be returned when the terminal was already online.
• status=fail means that the terminal could not switch back online or the request could not be completed.
• Integrators should use setOnlineResult to determine the SAF exit result and message for a human-readable explanation.

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!