☰

Navigation:

Batch request

An overview of the Batch request message for iOS.

Our ‘viva.com | Terminal’ application (tap-on-phone) supports Apple Tap to Pay in the UK, the Netherlands, France & Italy.

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

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:
Close Batch:

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!