POS Activation request
An overview of the POS Activation request message for Android.
- Overview
- POS Activation request
- POS Activation response
- Key to card terminal product categories
- Get Support
Overview
👉 The POS Activation request is used to complete the activation process of the ‘viva.com | Terminal’ 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.
- POS Activation request originating from the client app to trigger the POS activation.
- POS Activation response originating from the ‘viva.com | Terminal’ application to return the result of the POS activation request.
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' | ✅ | ![]() |
||
appId | The client app ID. For successful validation, should not be empty. | 'com.example.myapp' | ✅ | ![]() |
||
action | Activate POS action. For successful validation, should not be empty. | 'activatePos' | ✅ | ![]() |
||
callback | The URI callback that will handle the result. For successful validation, should not be empty. | 'mycallbackscheme://result' | ✅ | ![]() |
||
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“ | ✅ | ![]() |
||
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“ | ✅ | ![]() |
||
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 |
![]() |
|||
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 | ![]() |
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 |
![]() |
boolean | ||
activateMoto | Optional boolean parameter for activating Moto payment method. | The default value = false Example: false |
![]() |
boolean | ||
activateQRCodes | Optional boolean parameter for activating QR payment method. | The default value = false Example: false |
![]() |
boolean | ||
disableManualAmountEntry | Optional boolean parameter ( default value = false) for disabling manual amount entry | true | ![]() |
boolean | ||
forceCardPresentmentForRefund | Optional boolean parameter ( default value = false) for forcing card presentment for refund | true | ![]() |
boolean | ||
lockRefund | Optional boolean parameter ( default value = false) for locking refund with pin | true | ![]() |
boolean | ||
lockTransactionsList | Optional boolean parameter ( default value = false) for locking transaction list with pin | true | ![]() |
boolean | ||
lockMoto | Optional boolean parameter ( default value = false) for locking moto with pin | true | ![]() |
boolean | ||
lockPreauth | Optional boolean parameter ( default value = false) for locking preauth with pin | true | ![]() |
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 ‘viva.com | Terminal’ application 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' | ![]() |
status | The status of the transaction. | 'success' | ![]() |
message | A string containing information about the transaction status. Please see a list of possible error codes. |
'Transaction successful' | ![]() |
action | Activate POS action. | 'activatePos' | ![]() |
virtualId | App FirebaseId | '60DEC5165EBC41DEAAE693FD51B1F3FC' | ![]() |
sourceTerminalId | Optional parameter - Connected Terminal Id. | 16027706 | ![]() |
merchantID | Optional parameter - Activated Merchant Id. | `c21ac4b3-b1e1-4e7c-a65e-aedee7412321` | ![]() |
A POS activation response result for an approved transaction looks as follows:
mycallbackscheme://result?status=success&message=Pos%2520Activated&action=activatePos&sourceTerminalId=16027706&merchantId=c21ac4b3-b1e1-4e7c-a65e-aedee7412321&virtualId=60DEC5165EBC41DEAAE693FD51B1F3FC
It is expected that POS activation will fail for various reasons. A POS activation response looks as follows:
mycallbackscheme://result?status=fail&message=(-4) USER_CANCEL&action=activatePos
A POS activation response looks as follows when is already activated with the merchant:
vivawalletcallbackscheme://result?status=fail&message=POS_IS_ALREADY_ACTIVATED&action=activatePos&virtualid=XXxxXXxxXXxxXXXXxxXX &sourceTerminalid=11111111&merchantid=1a1a1a1a-1a1a1a1a-1a1a1a1a
Error codes
The following error codes may be displayed in the response to this request.
Code | Message |
---|---|
-4 | USER_CANCEL |
-14 | CONNECTION_ERROR |
-997 | AUTHORIZATION_PENDING |
-999 | UNEXPECTED |
-1000 | WRONG_PARAMETERS |
-1025 | DEMO_MODE_ERROR |
-2991 | NO_BUSINESS_ACCOUNT_FOUND |
-2994 | MISSING_USER_ACTIVATION_CODE |
-2997 | USER_CODE_EXPIRED |
-2998 | ACTIVATION_CODES_NOT_MATCH |
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 Wallet, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!