Barcode scanning

On Android payment terminals S1E Barcode, S1E2L, S1F2L, and S1U2 you can make use of barcode scanner. You use one of the following barcode scanning solutions:

• Enable barcode scanner button: When this feature is enabled, you can press the dedicated button on the terminal to activate the scanner. If it scans a barcode, the terminals pastes the barcode content into an Android app installed on the terminal that has an input text box. You can also enable the software keyboard feature where the terminal simulates typing the barcode content as individual characters. For this to work, your app needs to listen for software keyboard events.

• Use barcode scanner with Terminal API: To scan a barcode you need to send a request to activate the barcode scanner. You receive the barcode content in the response. You need to implement a way to process the content in your app.

Enable barcode scanner

You can enable barcode scanning per company, merchant accounts, store or terminal level:

1. Log into your Customer Area.
2. Go to Terminal Settings > Hardware > Barcode scanner.
3. Under Enable barcode scanner button, select Enabled.
4. To play a sound after a successful scan, under Play a beep select Enabled.
5. To place a separator after each scan, under Separator choose one of the following options:
   • New line: passes the content of each scanned barcode in a new line. This option is set by default.
   • Custom: in the Custom character field, specify the character that you want to use as a separator.
6. Select Save.

Additionally, you can contact our Support Team to enable:

• Adding a prefix to scanned barcodes. You need to provide the characters you want added in front of every scanned barcode content.
• Software keyboard feature, where the barcode content is typed into your Android app as individual keyboard events. With this integration, your app needs to listen for software keyboard events.

For advanced barcode-scanning use cases, see how you can activate the barcode scanner with a Terminal API request.

Use barcode scanner with Terminal API

If you want more control over how the barcode scanner is activated, cancelled, or the duration of the scan you can send Terminal API requests.
When you receive the barcode content in the response, you need to implement a way to process it in your app depending on your use case.

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

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.

1. 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).

2. Encode the JSON object to Base64.

3. 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.

4. 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.

5. 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.

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

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.

1. 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.

2. Encode the JSON object to Base64.

3. 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.

4. 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 scanner. 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

See also