Batch request

An overview of the Batch request message for Android.

• Overview
• Batch request
• Batch response
• Key to card terminal product categories
• Get Support

Overview

👉 The Batch request is used to either open a new batch (‘group’ of transactions) or to close an active batch in the Viva Terminal App. This is especially useful for reporting purposes.

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:

Field	Description	Example	Required	Card terminal support	Max Length	Type
scheme	The Viva's custom URL scheme, the host and the version.	'vivapayclient://pay/v1'	✅
merchantKey	The merchant's key. For successful validation, should not be empty. Deprecated: you may pass any value	'SG23323424EXS3'
appId	The client app ID. For successful validation, should not be empty.	'com.example.myapp'	✅
action	Batch.	'batch'	✅
callback	The URI callback that will handle the result. For successful validation, should not be empty.	'mycallbackscheme://result'	✅
command	Specifies the request action. “open” to create a new batch “close” to close the batch	‘open’	✅
batchId	For “open“ command this parameter is not used. For “close“ command, if this parameter is provided, Android POS tries to close the batch with this specific UUID. (Optional)	‘d3fdc9c5-2975-4612-bf52-8c43cd2eb1ba’			No limit (auto-populated with 36 random characters)
batchName	For “open“ command, if this parameter is provided it will be used as the batch name. If no value is provided, the batch will be named automatically. (Optional) For “close“ command, if this parameter is provided, it will be used in order to find an open batch with this name. (Optional)	‘20230401999999’

For “close” command, if neither “batchId” nor “batchName” are provided the command will be applied in the current active batch.

If a new batch is opened before the previously opened one is closed, the old one shall be closed and the new one will be opened.

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=20230401999999";

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);

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.

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.	'Batch successfully created!'
action	Batch.	'batch'
command	Specifies the request action. “open” to create a new batch “close” to close the batch	‘open’
batchId	The UUID of the batch that the command was applied on.	‘d3fdc9c5-2975-4612-bf52-8c43cd2eb1ba’
batchName	The name of the batch that the command was applied on.	20230401999999

A batch response result for opening a batch looks as follows:

A batch response result for closing a batch looks as follows:

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 Terminal App for Android	Mini Card Reader, Pocket Card Terminal connected via Bluetooth or USB to the Viva Terminal 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 Contact & Support page to see how we can help!