Batch request
An overview of the Batch request message for iOS.
Our ‘Viva.com Terminal’ application (tap-on-phone) supports Apple Tap to Pay Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Finland, France, Germany, Greece, Hungary, Ireland, Italy, Luxembourg, Malta, Poland, Portugal, Romania, Sweden, the Netherlands, the UK.
Overview
👉 The Batch request is used to either open a new batch (‘group’ of transactions) or to close an active batch in the Viva.com Terminal App. This is especially useful for reporting purposes.
On iOS 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 URL schemes and to receive the result in a custom URI callback.
- Batch request originating from the client app to open/close (if possible) a batch.
- Batch response originating from the Viva.com 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 |
---|---|---|
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. | 'com.example.myapp' |
action | Batch request. | 'batch' |
command | Specifies the request action: 'open' to create a new batch, 'close' to end an active batch. | 'open' |
batchName | When opening a new batch this name will be given to the batch. If no value is provided, the batch will be named automatically. When closing a batch this parameter will attempt to close any open batch with this specific name. If no value is provided, the currently active batch will end. (Optional) |
'morningShift' |
batchId | Works only when closing a batch. This parameter will attempt to close any open batch with this specific UUID. (Optional) | '7885F4F1-59CA-42C2-81BB-6DB48AA138A6' |
callback | The URI callback that will handle the result. | 'interapp-callback' |
// USE LIKE THIS
func createBatchRequest(command: String, batchName: String?, batchUUID: String?) {
// construct batch url
var endBatchActionURL = Constants.batchUrlString //vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=set_printing_settings
endBatchActionURL += "&command=" + command
if let batchName = batchName, batchName.isValidName {
endBatchActionURL += "&batchName=" + batchName // name of batch to end
}
if let batchUUID = batchUUID, batchUUID.isValidName {
endBatchActionURL += "&batchId=" + batchUUID // uuid of batch to end
}
(UIApplication.shared.delegate as? AppDelegate)?.performInterAppRequest(request: endBatchActionURL)
}
Examples
Open batch:
vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action=batch&command=open&batchName=morningShift
Close batch:
vivapayclient://pay/v1?callback=interapp-callback&merchantKey=SG23323424EXS3&appId=com.vivawallet.InterAppDemo&action&command=close=batch&batchName=morningShift
Batch response
After executing a Batch request the Viva.com Terminal App will respond accordingly to the type of command you sent.
The table below summarizes the contents of a response.
Field | Description | Example |
---|---|---|
callback | The URI callback that will handle the result. | 'interapp-callback://result' |
action | The action. | 'batch' |
command | Specifies the action taken: 'open' for creating a new batch, 'close' for ending an active batch. | 'close' |
batchName | The name of the batch opened/closed. | 'morningShift' |
batchId | The UUID of the batch opened/closed. | |
status | The status of the batch request. | 'success' |
message | A string containing information about the batch status. | 'Batch closed' |
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.
A Batch response result for an successful batch open or close looks as follows:
Examples
Open Batch:
interapp-callback://?status=success&message=Batch%2520successfully%2520created!&action=batch&batchName=morningShift&batchId=7885F4F1-59CA-42C2-81BB-6DB48AA138A6&command=open
Close Batch:
interapp-callback://?status=success&message=Batch%2520closed&action=batch&batchName=morningShift&batchId=7885F4F1-59CA-42C2-81BB-6DB48AA138A6&command=close
Get Support
If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!