Barcode scanning

Send Terminal API requests to scan barcodes with a payment terminal.

You can send a Terminal API request to a payment terminal to activate its barcode scanner. This only works for Android terminals that have a built-in barcode scanner: S1E Barcode, S1E2L, S1F2L, and S1U2.
You send a Terminal API AdminRequest with the ServiceIdentification field that turns on the barcode scanner for a set amount of time. If the barcode scanner camera detects a barcode before the timeout, it decodes the barcode and returns its content in the AdditionalResponse.additionalData. If the barcode scanner doesn't detect a barcode within the set amount of time, it turns off and you receive the timeout error in the response.
You then process the received barcode data in your system depending on your use case, for example to identify the scanned item at checkout.

This approach is suitable if you want more control over how barcode scanning is activated, cancelled, or the duration of the scan. For terminals with a dedicated barcode scanner button, like S1E2L, you can enable the barcode scanner button in your Customer Area.

How it works

Before you begin, make sure that you have built a local or cloud Terminal API integration.

To use the barcode scanner:

You send a Terminal API request to activate the barcode scanner.
You scan the barcode with the scanner on the payment terminal.
You process the barcode data from the response in your back-end system.

If you want to turn off the barcode scanner before the timeout, you need to send a request to cancel the scanning session.

Activate barcode scanner

To scan a barcode you only need to send a request to activate the barcode scanner. On a successful scan, there is no need to end the session.

Create a JSON object with the following data elements:

Parameter	Required	Description
`Session`		An object with: `Id`: your unique reference of the scanning session. `Type`: Once activates the barcode scanner.
`Operation`		An object with: `Type`: ScanBarcode. `TimeoutMs`: how long the barcode scanner stays on, in milliseconds (from 0 to 30000).

Encode the JSON object to Base64.

Make a POST request to a Terminal API endpoint, specifying:

MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

Parameter	Required	Description
`ProtocolVersion`		3.0
`MessageClass`		Service
`MessageCategory`		Admin
`MessageType`		Request
`ServiceID`		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (`POIID`) being used.
`SaleID`		Your unique ID for the POS system component to send this request from.
`POIID`		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

AdminRequest: the request body. This must include:
- ServiceIdentification: the Base64-encoded JSON object.

In the response, note:

If successful, the following fields are returned:
- Response.Result: Success
- AdditionalResponse: contains the Base64-encoded barcode content.
If unsuccessful, the following fields are returned:
- Response.Result: Failure
- ErrorCondition: Cancel, Aborted, UnavailableService, or NotFound
- AdditionalResponse: contains the reason for failure as a Base64-encoded string. Decoding the string results in a message of the following format: { "message": "Admin ScanBarcode request canceled due to Timeout" }.

The format of the AdditionalResponse can be a Base64-encoded or URL-encoded. To always receive the AdditionalResponse in one of those formats, contact our Support Team.

{
    "SaleToPOIResponse": {
        "AdminResponse": {
            "Response": {
                "Result": "Success",
                 "AdditionalResponse": "eyAiQmFyY29kZSI6IHsgIkRhdGEiOiAiODYwMDE5NzQxNjgyNCIsICJTeW1ib2xvZ3kiOiAiUVJfQ09ERSIgfSB9"
            }
        },
        "MessageHeader": {
            "MessageCategory": "Admin",
            "MessageClass": "Service",
            "MessageType": "Response",
            "POIID": "S1EL-324688179",
            "ProtocolVersion": "3.0",
            "SaleID": "POSSystemID12345",
            "ServiceID": "S00101"
        }
    }
}

{
    "SaleToPOIResponse": {
        "AdminResponse": {
            "Response": {
                "AdditionalResponse": "eyAibWVzc2FnZSI6ICJBZG1pbiBTY2FuQmFyY29kZSByZXF1ZXN0IGNhbmNlbGVkIGR1ZSB0byBUaW1lb3V0IiB9",
                   "ErrorCondition": "Cancel",
                   "Result": "Failure"
            }
        },
           "MessageHeader": {
            "ProtocolVersion": "3.0",
            "MessageClass": "Service",
            "MessageCategory": "Admin",
            "MessageType": "Request",
            "ServiceID": "POSSystemID12345",
            "SaleID": "S00101",
            "POIID": "S1EL-324688179"
        }
    }
}

If Response.Result is Success, decode the Base64-encoded string in the AdditionalResponse.
Note that this contains:
- Barcode.Data: the content of the scanned barcode.
- Barcode.Symbology: the format of the scanned barcode. If the symbology is not recognized, the response returns UNKNOWN.
For more information on the Terminal API request structure, see the Terminal API fundamentals.

Cancel scanning session

If you want to cancel the activation of the terminal's barcode scanner before the specified timeout, you need to send an AdminRequest with the Session.Type End.

Create a JSON object with the following data elements:
Parameter Required Description
ServiceIdentification.Session
An object with:
Id: the unique reference of the session.

Type: End cancels the scanning session.
Encode the JSON object to Base64.

Make a POST request to a Terminal API endpoint, specifying:

MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

Parameter	Required	Description
`ProtocolVersion`		3.0
`MessageClass`		Service
`MessageCategory`		Admin
`MessageType`		Request
`ServiceID`		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (`POIID`) being used.
`SaleID`		Your unique ID for the POS system component to send this request from.
`POIID`		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

AdminRequest: the request body. This must include:
- ServiceIdentification: the Base64-encoded JSON object.

If the cancel request succeeds, in the AdminResponse note:
- Response.Result: Success
- AdditionalResponse: contains the Base64-encoded message. Decoding the string results in a message of the following format: { "message": "Admin ScanBarcode request was successfully canceled" }
The format of the AdditionalResponse can be a Base64-encoded or URL-encoded. To always receive the AdditionalResponse in one of those formats, contact our Support Team.

Barcode symbologies

Symbologies are barcode formats that a payment terminal can recognize, and they depend on the decoder of the barcode-scanning camera. If the barcode is scanned successfully but the symbology is not recognized, the response still returns the content inside Barcode.Data, but the Barcode.Symbology is UNKNOWN.

Our payment terminals recognize the following barcode symbologies:

	S1E Barcode	S1E2L	S1F2L	S1U2
CODABAR
CODE 128
CODE 39
Data Matrix
EAN-8
EAN-13
GS1
Matrix 2 of 5
MaxiCode
PDF417
QR Code
UPC-A
UPC-E