Batch request
An overview of the Batch request message for Android.
Overview
👉 The Batch request is used to either open a new batch (‘group’ of transactions) or to close an active batch in the POS application. This is especially useful for reporting purposes.
On Android devices (Tap-on-Phone), a batch remains open for 48 hours before automatically being closed and a new one being started (unless the user ends it manually before this time)
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.
- Batch request originating from the client app to open or close a batch.
- Batch response originating from the card terminal app to return the result of a Batch request.
Batch request
For a typical Batch request, the client app must provide the following information:
For “close” and “printSummary“ commands if neither “batchId” nor “batchName” are provided the command will be applied in the current active batch.
In order to open a new batch, the above information elements must create a URI call, i.e.
String reqStr = "vivapayclient://pay/v1"
+ "?merchantKey="MY_MERCHANT_KEY"
+ "&appId=com.example.myapp"
+ "&action=batch"
+ "&callback=mycallbackscheme://result"
+ "&command=open"
+ "&batchName=shift";
Intent payIntent = new Intent(Intent.ACTION_VIEW, Uri.parse(reqStr));
payIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
payIntent.addFlags(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
startActivity(payIntent);
In order to close an active batch, the above information elements must create a URI call, i.e.
String reqStr = "vivapayclient://pay/v1"
+ "?merchantKey="MY_MERCHANT_KEY"
+ "&appId=com.example.myapp"
+ "&action=batch"
+ "&callback=mycallbackscheme://result"
+ "&command=close";
Intent payIntent = new Intent(Intent.ACTION_VIEW, Uri.parse(reqStr));
payIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
payIntent.addFlags(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
startActivity(payIntent);
In order to print the summary of an active batch, the above information elements must create a URI call, i.e.
String reqStr = "vivapayclient://pay/v1"
+ "?merchantKey="MY_MERCHANT_KEY"
+ "&appId=com.example.myapp"
+ "&action=batch"
+ "&callback=mycallbackscheme://result"
+ "&command=printSummary";
Intent payIntent = new Intent(Intent.ACTION_VIEW, Uri.parse(reqStr));
payIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
payIntent.addFlags(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS);
startActivity(payIntent);
Batch response
After executing a batch request, the Card Terminal App responds with a batch response result to indicate if the batch request has been 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.
A batch response result for opening a batch looks as follows:
mycallbackscheme://result?status=success&message=Batch successfully created!&action=batch&command=open&batchId=d3fdc9c5-2975-4612-bf52-8c43cd2eb1ba&batchName=shift
A batch response result for closing a batch looks as follows:
mycallbackscheme://result?status=success&message=Batch successfully closed!&action=batch&command=close&batchId=d3fdc9c5-2975-4612-bf52-8c43cd2eb1ba&batchName=shift
A batch response result for printing the summary of a batch looks as follows:
mycallbackscheme://result?status=success&message=Batch summary successfully printed!&action=batch&command=printSummary&batchId=d3fdc9c5-2975-4612-bf52-8c43cd2eb1ba&batchName=shift
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 Wallet POS app for Android | Mini Card Reader, Pocket Card Terminal connected via Bluetooth or USB to the Viva Wallet POS app 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 Get Support page to see how we can help!