Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

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, like the S1E Barcode terminal.
You send an 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.message. If he 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 the till or

How it works

  1. You send a request to activate the barcode scanner.
  2. Scan the barcode with the scanner on the payment terminal.
  3. 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.

  1. Create a JSON object with the following data elements:

    Parameter Required Description
    Session -white_check_mark- An object with:
    • Id: your unique reference of the scanning session.
    • Type: Once activates the barcode scanner.
    Operation -white_check_mark- An object with:
    • Type: ScanBarcode.
    • TimeoutMs: how long the barcode scanner stays on, in milliseconds.
    Activate barcode scanner
    {
        "Session": {
            "Id": 12345,
            "Type": "Once"
        },
        "Operation": [
            {
                "Type": "ScanBarcode",
                "TimeoutMs": 5000
            }
        ]
    }
  2. Encode the JSON object to Base64.

    Base64 encoded message
    ewogICAgIlNlc3Npb24iOnsKICAgICAgICAiSWQiOjEyMzQ1LAogICAgICAgICJUeXBlIjoiT25jZSIKICAgIH0sCiAgICAiT3BlcmF0aW9uIjpbCiAgICAgICAgewogICAgICAgICAgICAiVHlwZSI6IlNjYW5CYXJjb2RlIiwKICAgICAgICAgICAgIlRpbWVvdXRNcyI6NTAwMAogICAgICAgIH0KICAgIF0KfQ==
  3. Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. This includes:
      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Admin
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- Your unique ID for this request.
      SaleID -white_check_mark- Your unique ID for the system where you send this request from.
      POIID -white_check_mark- The unique ID of the terminal that you send this request to.
    • AdminRequest: the request body. This must include:
      • ServiceIdentification: the Base64-encoded JSON object.
    Activate barcode scanner request
    {
       "SaleToPOIRequest": {
          "MessageHeader": {
             "ProtocolVersion": "3.0",
             "MessageClass": "Service",
             "MessageCategory": "Admin",
             "MessageType": "Request",
             "ServiceID": "POSSystemID12345",
             "SaleID": "S00101",
             "POIID": "S1EL-324688179"
          },
          "AdminRequest": {
             "ServiceIdentification": "ewogICAgIlNlc3Npb24iOnsKICAgICAgICAiSWQiOjEyMzQ1LAogICAgICAgICJUeXBlIjoiT25jZSIKICAgIH0sCiAgICAiT3BlcmF0aW9uIjpbCiAgICAgICAgewogICAgICAgICAgICAiVHlwZSI6IlNjYW5CYXJjb2RlIiwKICAgICAgICAgICAgIlRpbWVvdXRNcyI6NTAwMAogICAgICAgIH0KICAgIF0KfQ=="
           }
       }
    }
  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:
      • AdditionalResponse: contains the reason for failure, such as canceled due to timeout.
    {
        "SaleToPOIResponse": {
            "AdminResponse": {
                "Response": {
                    "Result": "Success",
                     "AdditionalResponse": "message=eyAiQmFyY29kZSI6IHsgIkRhdGEiOiAiODYwMDE5NzQxNjgyNCIsICJTeW1ib2xvZ3kiOiAiUVJfQ09ERSIgfSB9"
                }
            },
            "MessageHeader": {
                "MessageCategory": "Admin",
                "MessageClass": "Service",
                "MessageType": "Response",
                "POIID": "S1EL-324688179",
                "ProtocolVersion": "3.0",
                "SaleID": "POSSystemID12345",
                "ServiceID": "S00101"
            }
        }
    }
  5. If Response.Result is Success, decode the Base64-encoded message 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.
    Decoded Base64 AdditionalResponse
    {
       "Barcode":{
           "Data":"8600197416824",
           "Symbology":"QR_CODE"
       }
    }

    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.

  1. Create a JSON object with the following data elements:

    Parameter Required Description
    ServiceIdentification.Session -white_check_mark- An object with:
    • Id: the unique reference of the session.
    • Type: End cancels the scanning session.
    Data elements in JSON format
    {
        "Session": {
            "Id": 12345,
            "Type": "End"
        }
    }
  2. Encode the JSON object to Base64.

    Base64 encoded message
    ewogICAiU2Vzc2lvbiI6ewogICAgICAiSWQiOjEyMzQ1LAogICAgICAiVHlwZSI6IkVuZCIKICAgfQp9
  3. Make a POST request to a Terminal API endpoint, specifying:

    • AdminRequest: the request body. This must include:
      • ServiceIdentification: the Base64-encoded JSON object.
    End scanning session
    {
       "SaleToPOIRequest":{
          "MessageHeader":{
             "ProtocolVersion":"3.0",
             "MessageClass":"Service",
             "MessageCategory":"Admin",
             "MessageType":"Request",
             "ServiceID":"S00101",
             "SaleID":"POSSystemID12345",
             "POIID":"S1EL-324688179"
          },
          "AdminRequest":{
             "ServiceIdentification": "ewogICAiU2Vzc2lvbiI6ewogICAgICAiSWQiOjEyMzQ1LAogICAgICAiVHlwZSI6IkVuZCIKICAgfQp9"
           }
       }
    }
  4. The AdminResponse shows Response.Result Success, with AdditionalResponse.message confirming that the request was successfully canceled.

    End scanning session response - success
    {
        "SaleToPOIResponse": {
            "MessageHeader": {
            "ProtocolVersion": "3.0",
            "MessageClass": "Service",
            "MessageCategory": "Admin",
            "MessageType": "Request",
            "ServiceID": "POSSystemID12345",
            "SaleID": "S00101",
            "POIID": "V400m-324688179"
            },
            "AdminResponse": {
                "Response": {
                    "Result": "Success",
                    "AdditionalResponse": "message=Admin%20ScanBarcode%20request%20was%20successfully%20canceled"
                }
            }
        }
    }

Barcode symbologies

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

S1E Barcode payment terminal recognizes the following barcode symbologies:

  • 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