Sale request
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.
- 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.
Sale request
For a typical sale request the client app must provide the following information:
ISV parameter info:
- ISV_clientId can be found under Settings > API access in the Viva Wallet banking app
- ISV_clientSecret as above.
- ISV_sourceCode is the payment source for stores set up under Sales > Physical Payments > Stores.
The above parameters must be used to create a URI call. Please see the below examples:
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"
+ "&show_receipt="+true
+ "&show_transaction_result="+true
+ "&show_rating="+true
+ "&ISV_amount="+100
+ "&ISV_clientId=qwerty123456"
+ "&ISV_clientSecret=qwerty123456"
+ "&ISV_sourceCode=qwerty123456"
+ "&callback=mycallbackscheme://result"));
payIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
payIntent.addFlags(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
startActivity(payIntent);
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"
+ "&show_receipt="+true
+ "&show_transaction_result="+true
+ "&show_rating="+true
+ "&withInstallments="+true
+ "&preferredInstallments="+10
+ "&ISV_amount="+100
+ "&ISV_clientId=qwerty123456"
+ "&ISV_clientSecret=qwerty123456"
+ "&ISV_sourceCode=qwerty123456"
+ "&callback=mycallbackscheme://result"));
payIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
payIntent.addFlags(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
startActivity(payIntent);
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.
A sale response result for an approved transaction looks as follows:
mycallbackscheme://result?status=success&message=Transaction successful&action=sale&clientTransactionId=1234567801234&amount=1200&tipAmount=0&verificationMethod=CONTACTLESS - NO CVM&rrn=107715996464&cardType=Debit Mastercard&referenceNumber=996464&accountNumber=537488******9666&authorisationCode=006593&tid=16000223&orderCode=1077172694000223&shortOrderCode=1077172694&transactionDate=2021-03-18T17:07:51.1888432+02:00&transactionId=2161282c-3989-4089-80f1-2ac555dc5f63
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=fail&message=(-12) TRANSACTION_DECLINED_BY_SERVER&action=sale&clientTransactionId=1234567801234&amount=101&tipAmount=0&verificationMethod=CONTACTLESS - NO CVM&rrn=107715996469&cardType=Debit Mastercard&referenceNumber=996469&accountNumber=537488******9666&tid=16000223&orderCode=1077172696000223&shortOrderCode=1077172696&transactionDate=2021-03-18T17:09:13.1917889+02:00&transactionId=3ca278e7-0679-411e-8279-ebb29ee519b2
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.
POS Entry Mode Enumeration
Entry Mode | Value |
---|---|
NONE | '00' |
MANUAL ENTRY | '01' |
MAGSTRIPE PAN | '02' |
BAR CODE READER | '03' |
OCR | '04' |
CHIP | '05' |
CONTACTLESS CHIP | '07' |
CONTACTLESS MAGSTRIPE | '91' |
MAGSTRIPE | '90' |
FALLBACK | '80' |
MOTO | '09' |
Get Support
If you have any questions about our solutions, or questions about how to integrate with our solutions, please refer to our Get Support page.