POS Activation request

An overview of the POS Activation request message for Android.

Overview

👉 The POS Activation request is used to complete the activation process of the POS application, including sign-in and initial configuration.

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.

To use this feature, you will need to generate and use the required POS APIs Credentials

POS Activation request

For a typical POS Activation request, the client app must provide the following information:

Field Description Example Required Card terminal support Character limit Type
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 the POS will be assigned to. Not required for successful validation [A payment source (physical store) that is associated with a terminal]

How to create a payment source for stores
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 Min. length = 4
Max. length = 6
integer (int32)
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 boolean
activateMoto Optional boolean parameter for activating Moto payment method. The default value = false

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

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

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"
                        + "&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 Contact & Support page to see how we can help!