POS terminal app

The Viva Wallet card terminal app for Android can receive requests for initiating transactions from third-party apps installed on the same Android mobile device. Communication with the card terminal app is done by using Android intents. The client app creates an intent with parameters and starts the card terminal app’s pay activity. When the card terminal app’s pay activity finishes it returns the result to the caller app.

Get it on Google Play

A sample app is also available for download from our public GitHub account. It demonstrates the inter-app communication ability and contains all the necessary Gradle build files.

Messages

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. Overall the following messages are available:

  • Sale Request originating from the client app to initiate a request for a new Sale transaction.
  • Sale Response originating from the Card terminal app to return the result of a Sale transaction.
  • Cancel Request originating from the client app to initiate a request for a Cancel transaction.
  • Cancel Response originating from the Card terminal app to return the result of a Cancel transaction.

Callback activity

The client app must provide a callback activity declare in AndroidManifest.xml, in order to receive the response results.

<activity
          android:name="com.example.URLResponseActivity"
          android:label="Payment Result">
            <intent-filter>
                <action android:name="android.intent.action.VIEW"/>
                <action android:name="com.example.URLResponseActivity"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
                <!-- Provide your own scheme here and reference it when you send a message -->
                 <data
                   android:scheme="mycallbackscheme"
                   android:host="result"/>
            </intent-filter>
        </activity>

Sale Request

For a typical sale request the client app must provide the following information:

Field Description Example
scheme The Viva's custom URL scheme, the host and the version 'vivapayclient://pay/v1'
merchantKey The merchant's key 'SG23323424EXS3'
appId The client app id 'com.example.myapp'
action Sale transaction 'sale'
clientTransactionId A unique transaction ID transmitted to the host for storage with the transaction. Note that this value will be provided in the MerchantTrns field provided in the sales export response. '12345678901234567890123456789012'
amount Amount in cents without any decimal digits. '1200' = 12 euro
tipAmount How much of the amount in cents is considered as tip without any decimal digits. '200' = 2 euro
callback The URI callback that will handle the result. '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"
                                + "?merchantKey="MY_MERCHANT_KEY""
                                + "&appId=com.example.myapp"
                                + "&action=sale"
                                + "&clientTransactionId=1234567801234"
                                + "&amount=1200"
                                + "&tipAmount=200"
                                + "&callback=mycallbackscheme://result"));

payIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
                startActivity(payIntent);

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

Uri result = getIntent().getData()

Sale Response

After executing a Sale transaction the card terminal app responds with a Sale Response result to indicate if the transaction has been approved 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
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. 'Transaction successful'
action Sale transaction 'sale'
clientTransactionId The client transaction ID. '12345678901234567890123456789012'
amount The amount in cents without any decimal digits. '1200' = 12 euro
tipAmount How much of the amount in cents is considered as tip without any decimal digits. '200' = 2 euro
verificationMethod The verification method used 'CHIP-PIN'
rrn The retrieval reference number of the transaction RRN. '123456833121'
cardType The card type. 'VISA'
accountNumber The card number masked. Note that only the 6 first and the 4 last digits are provided. All other digits are masked with stars. '479275******9999'
referenceNumber A 6-digit number indicating the transaction's STAN number. '833121'
authorisationCode A 6-digit number indicating the transaction's Authorisation code provided by the host. '690882'
tid A 12 character string indicating the terminal's TID number. ' 16016684'

A Sale response result for an approved transaction looks as follows:

mycallbackscheme://result?status=success&message=Transaction%20successful.&action=sale&clientTransactionId=12345678901234567890123456789012&amount=1200&tipAmount=200&verificationMethod= CHIP-PIN&rrn=123456833121&cardType=VISA& accountNumber=479275******9999&referenceNumber=833121&authorisationCode =690882&tid=16016684

It is expected that certain transactions will fail for various reasons. A Sale response result for a failed transaction looks as follows:

mycallbackscheme://result?status=failed&message=Transaction%20declined%20by%20host.&action=sale&clientTransactionId=12345678901234567890123456789012&amount=1200&tipAmount=200&verificationMethod=CHIP-PIN&rrn=123456833121&cardType=VISA& accountNumber=479275******9999& referenceNumber=&authorisationCode=&tid=16016684

The structure of the message is the same as in the case of an approved transaction. Fields such as referenceNumber and authorisationCode may not have values since there is no STAN code available, nor an authorisation code.

Cancel Request

For a typical cancel request the client app must provide the following information:

Field Description Example
scheme The Viva's custom URL scheme, the host and the version. 'vivapayclient://pay/v1'
merchantKey The merchant's key. 'SG23323424EXS3'
appId The client app id. 'com.example.myapp'
action Cancel transaction. 'cancel'
clientTransactionId A unique transaction ID transmitted to the host for storage with the transaction. Note that this value will be provided in the MerchantTrns field provided in the sales export response. '12345678901234567890123456789012'
amount Amount in cents without any decimal digits. '1200' = 12 euro
referenceNumber The STAN number of the transaction to be cancelled. Currently not used. If empty, after card presentment, the app will provide a list of the last 3 transactions made with the presented card, allowing the user to select the transaction to be canceled.
callback The URI callback that will handle the result. '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"
                                + "?merchantKey="MY_MERCHANT_KEY""
                                + "&appId=com.example.myapp"
                                + "&action=cancel"
                                + "&clientTransactionId=1234567801234"
                                + "&amount=1200"
                                + "&callback=mycallbackscheme://result"));

payIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
                startActivity(payIntent);

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

Uri result = getIntent().getData()

Cancel Response

After executing a Cancel transaction the card terminal app responds with a Cancel Response result to indicate if the transaction has been approved 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
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. 'Transaction successful'
action Cancel transaction. 'cancel'
clientTransactionId The client transaction ID. '12345678901234567890123456789012'
amount The amount in cents without any decimal digits. '1200' = 12 euro
tipAmount How much of the amount in cents is considered as tip without any decimal digits. '200' = 2 euro
cardType The card type. 'VISA'
accountNumber The card number. Note that only the 6 first and the 4 last digits are provided. All other digits are masked with stars. '479275******9999'
tid A 12 character string indicating the terminal's TID number. ' 16016684'

A Cancel response result for an approved transaction looks as follows:

mycallbackscheme://result?status=success&message=Transaction%20successful.&action=cancel&clientTransactionId=12345678901234567890123456789012&amount=1200&tipAmount=200&cardType=VISA&accountNumber=479275******9999&tid=16016684

It is expected that certain transactions will fail for various reasons. A Cancel response result for a failed transaction looks as follows:

mycallbackscheme://result?status=success&message=Transaction%20successful.&action=cancel&clientTransactionId=12345678901234567890123456789012&amount=1200&tipAmount=200&cardType=VISA&accountNumber=479275******9999&tid=16016684

The structure of the message is the same as in the case of an approved transaction.