POS Activation request

An overview of the POS Activation message.

Overview

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.

This feature is only supported in Viva Wallet’s Production environment (VW POS app). The VW POS Demo environment cannot be used to carry out tests for this integration.

To test this feature in the Viva Wallet Production environment, you can reach out to your technical support (TAM) team via email or chat during your integration. Alternatively, please contact your sales representative in order to obtain the required API credentials

POS Activation request

With the POS Activation action the user can activate the POS. For a typical POS activation 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' Viva Wallet POS app for Android
appId The client app ID. For successful validation, should not be empty. 'com.example.myapp' Viva Wallet POS app for Android
action Activate POS action. For successful validation, should not be empty. 'activatePos' Viva Wallet POS app for Android
callback The URI callback that will handle the result. For successful validation, should not be empty. 'mycallbackscheme://result' Viva Wallet POS app for Android
apikey The API key ('Client ID') required for the POS activation. For successful validation, this should not be empty. You can find this credential here. “qwerty123456“ Viva Wallet POS app for Android
apiSecret The API Secret ('Client secret') required for the POS activation. For successful validation, this should not be empty. You can find this credential here. “qwerty123456“ Viva Wallet POS app for Android
sourceID The source that POS will be assigned to. Not required for succesfull validation. If not provided “Default” source will be used “qwerty123456“ Viva Wallet POS app for Android
pinCode Optional parameter (4-6 digits length) for PIN code for settings lock (if provided, settings are automatically locked and PIN set to the supplied value) 123142 Viva Wallet POS app for Android
skipExternalDeviceSetup Optional boolean parameter. Skip external device configuration (Mini card reader or Pocket Card terminal) and proceed with **NFC payment method** for transactions. The default value = true

Example: true
Viva Wallet POS app for Android
activateMoto Optional boolean parameter for activating Moto payment method. The default value = false

Example: false
Viva Wallet POS app for Android
activateQRCodes Optional boolean parameter for activating QR payment method. The default value = false

Example: false
Viva Wallet POS app for Android
disableManualAmountEntry Optional boolean parameter ( default value = false) for disabling manual amount entry true Viva Wallet POS app for Android
forceCardPresentmentForRefund Optional boolean parameter ( default value = false) for forcing card presentment for refund true Viva Wallet POS app for Android
lockRefund Optional boolean parameter ( default value = false) for locking refund with pin true Viva Wallet POS app for Android
lockTransactionsList Optional boolean parameter ( default value = false) for locking transaction list with pin true Viva Wallet POS app for Android
lockMoto Optional boolean parameter ( default value = false) for locking moto with pin true Viva Wallet POS app for Android
lockPreauth Optional boolean parameter ( default value = false) for locking preauth with pin true Viva Wallet POS app for Android

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=activatePos"
                        + "&apikey=qwerty123456"
                        + "&apiSecret=qwerty123456"
                        + "&activationCode=23110345"
                        + "&sourceID=qwerty123456"
                        + "&pinCode=123142"
                        + "&skipExternalDeviceSetup=true" +
                        + "&activateMoto=true"
                        + "&activateQRCodes=true"
                        + "&disableManualAmountEntry=true"
                        + "&forceCardPresentmentForRefund=true"
                        + "&lockRefund=true"
                        + "&lockTransactionsList=true"
                        + "&lockMoto=true"
                        + "&lockPreauth=true"
                        + "&callback=mycallbackscheme://result"));

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

POS Activation response

After executing a POS activation, the Card Terminal App responds with a POS activation response result to indicate if the POS activation was successful or not.

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

Uri result = getIntent().getData();

The table below summarizes the contents of an approved response.

Field Description Example Card terminal support
callback The URI callback that will handle the result. 'mycallbackscheme://result' Viva Wallet POS app for Android
status The status of the transaction. 'success' Viva Wallet POS app for Android
message A string containing information about the transaction status. 'Transaction successful' Viva Wallet POS app for Android
action Activate POS action. 'activatePos' Viva Wallet POS app for Android
virtualId App FirebaseId '60DEC5165EBC41DEAAE693FD51B1F3FC' Viva Wallet POS app for Android
sourceTerminalId Optional parameter - Connected Terminal Id. 16027706 Viva Wallet POS app for Android
merchantID Optional parameter - Activated Merchant Id. `c21ac4b3-b1e1-4e7c-a65e-aedee7412321` Viva Wallet POS app for Android

A POS activation response result for an approved transaction looks as follows:

It is expected that POS activation will fail for various reasons. A POS activation response looks as follows:

A POS activation response looks as follows when is already activated with the merchant:

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. Android Card Terminals
Viva Wallet POS app for Android Mini Card Reader, Pocket Card Terminal connected via Bluetooth or USB to the Viva Wallet POS app for Android. Android Card Terminals
Linux Card Terminals Countertop, IM20, S900, S800, D200. Linux Card Terminals

Get Support

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