--- title: "Activate scanning a single barcode using Terminal API" description: "Create a scanning session to scan a single barcode." url: "https://docs.adyen.com/point-of-sale/android-terminals/scan-barcode/single-session" source_url: "https://docs.adyen.com/point-of-sale/android-terminals/scan-barcode/single-session.md" canonical: "https://docs.adyen.com/point-of-sale/android-terminals/scan-barcode/single-session" last_modified: "2025-04-24T10:30:00+02:00" language: "en" --- # Activate scanning a single barcode using Terminal API Create a scanning session to scan a single barcode. [View source](/point-of-sale/android-terminals/scan-barcode/single-session.md) ##### Multiple barcodes To scan multiple barcodes instead of a single barcode, you can start a [batch scan session](/point-of-sale/android-terminals/scan-barcode/batch-session). On Android payment terminals [S1E Barcode](/point-of-sale/user-manuals/s1e-user-manual), [S1E2L](/point-of-sale/user-manuals/s1e2l-user-manual), [S1F2L](/point-of-sale/user-manuals/s1f2-user-manual), and [S1U2](/point-of-sale/user-manuals/s1u2-user-manual) you can use Terminal API requests to: * Activate the scan button on the terminal so that your staff can scan a single item. * Cancel scanning to deactivate the barcode scanner and the scan button. * Specify how much time you want to allow for scanning. You do not need to [set up the scanning button](/point-of-sale/android-terminals/scan-barcode/button-scan) in the Customer Area to use this method. ## Requirements Before you begin, take into account the following requirements, limitations, and preparations. | Requirement | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Integration type** | A [Terminal API integration](/point-of-sale/design-your-integration/terminal-api/) with payment terminals. | | **Hardware** | Android payment terminal models [S1E Barcode](/point-of-sale/user-manuals/s1e-user-manual), [S1E2L](/point-of-sale/user-manuals/s1e2l-user-manual), [S1F2L](/point-of-sale/user-manuals/s1f2-user-manual), or [S1U2](/point-of-sale/user-manuals/s1u2-user-manual) that have a barcode scanner. | | **Setup steps** | Before you begin:- You need to implement a way to process the scanned content in your POS app. - Implement a button in your POS app UI to trigger the scan. | ## How it works 1. You send an admin request to activate the barcode scanner. 2. Your staff scans an item. 3. A successful scan deactivates the barcode scanning button, and you receive the barcode content in the response to the admin request. 4. With the logic that you have created, you pass the content from the response to your POS app. ## Activate the barcode scanner for a single scan To activate the barcode scanner for a single scan, you only need to send a request. 1. Create a JSON object with the following data elements: | Parameter | Required | Description | | ----------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `Session` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Id`: your unique reference of the scanning session. - `Type`: **Once** activates the barcode scanner. | | `Operation` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Type`: **ScanBarcode**. - `TimeoutMs`: how long the barcode scanner stays on, in milliseconds (from 0 to 30000). | **Activate barcode scanner** ```json { "Session": { "Id": 12345, "Type": "Once" }, "Operation": [ { "Type": "ScanBarcode", "TimeoutMs": 5000 } ] } ``` 2. Encode the JSON object to Base64. **Base64 encoded message** ```raw ewogICAgIlNlc3Npb24iOnsKICAgICAgICAiSWQiOjEyMzQ1LAogICAgICAgICJUeXBlIjoiT25jZSIKICAgIH0sCiAgICAiT3BlcmF0aW9uIjpbCiAgICAgICAgewogICAgICAgICAgICAiVHlwZSI6IlNjYW5CYXJjb2RlIiwKICAgICAgICAgICAgIlRpbWVvdXRNcyI6NTAwMAogICAgICAgIH0KICAgIF0KfQ== ``` 3. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) admin request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Admin**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Admin** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | 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` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [AdminRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/admin) object, including: * `ServiceIdentification`: The Base64-encoded JSON object. **Activate barcode scanner request** ```json { "SaleToPOIRequest": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Admin", "MessageType": "Request", "ServiceID": "POSSystemID12345", "SaleID": "S00101", "POIID": "S1EL-324688179" }, "AdminRequest": { "ServiceIdentification": "ewogICAgIlNlc3Npb24iOiB7CiAgICAgICAgIklkIjogMTIzNDUsCiAgICAgICAgIlR5cGUiOiAiQmVnaW4iCiAgICB9LAogICAgIk9wZXJhdGlvbiI6IFsKICAgICAgICB7CiAgICAgICAgICAgICJUeXBlIjogIlNjYW5CYXJjb2RlIiwKICAgICAgICAgICAgIlRpbWVvdXRNcyI6IDUwMDAKICAgICAgICB9CiAgICBdCn0=" } } } ``` The terminal operator can now scan a barcode. 4. In the [AdminResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/admin#responses-200-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](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other). ### Tab: Activate barcode scanner response - success ```json { "SaleToPOIResponse": { "AdminResponse": { "Response": { "Result": "Success", "AdditionalResponse": "eyAiQmFyY29kZSI6IHsgIkRhdGEiOiAiODYwMDE5NzQxNjgyNCIsICJTeW1ib2xvZ3kiOiAiUVJfQ09ERSIgfSB9" } }, "MessageHeader": { "MessageCategory": "Admin", "MessageClass": "Service", "MessageType": "Response", "POIID": "S1EL-324688179", "ProtocolVersion": "3.0", "SaleID": "POSSystemID12345", "ServiceID": "S00101" } } } ``` ### Tab: Activate barcode scanner response - failure ```json { "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" } } } ``` 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](/point-of-sale/android-terminals/scan-barcode#barcode-symbologies) is not recognized, the response returns `UNKNOWN`. **Decoded Base64 AdditionalResponse** ```json { "Barcode":{ "Data":"8600197416824", "Symbology":"QR_CODE" } } ``` 6. You process the content from the response in your POS app with the logic that you have implemented. If you want to turn off the barcode scanner before the timeout, you need to send a request to [cancel the scanning session](#cancel-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` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Id`: the unique reference of the session. - `Type`: **End** cancels the scanning session. | **Data elements in JSON format** ```json { "Session": { "Id": 12345, "Type": "End" } } ``` 2. Encode the JSON object to Base64. **Base64 encoded message** ```raw ewogICAiU2Vzc2lvbiI6ewogICAgICAiSWQiOjEyMzQ1LAogICAgICAiVHlwZSI6IkVuZCIKICAgfQp9 ``` 3. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) admin request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Admin**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Admin** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | 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` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [AdminRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/admin) object, including: * `ServiceIdentification`: the Base64-encoded JSON object. **End scanning session** ```json { "SaleToPOIRequest":{ "MessageHeader":{ "ProtocolVersion":"3.0", "MessageClass":"Service", "MessageCategory":"Admin", "MessageType":"Request", "ServiceID":"S00101", "SaleID":"POSSystemID12345", "POIID":"S1EL-324688179" }, "AdminRequest":{ "ServiceIdentification": "ewogICAiU2Vzc2lvbiI6ewogICAgICAiSWQiOjEyMzQ1LAogICAgICAiVHlwZSI6IkVuZCIKICAgfQp9" } } } ``` 4. If the cancel request succeeds, in the [AdminResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/admin#responses-200-Response) 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" }` **End scanning session response - success** ```json { "SaleToPOIResponse": { "MessageHeader": { "ProtocolVersion": "3.0", "MessageClass": "Service", "MessageCategory": "Admin", "MessageType": "Request", "ServiceID": "POSSystemID12345", "SaleID": "S00101", "POIID": "V400m-324688179" }, "AdminResponse": { "Response": { "Result": "Success", "AdditionalResponse": "eyAibWVzc2FnZSI6ICJBZG1pbiBTY2FuQmFyY29kZSByZXF1ZXN0IHdhcyBzdWNjZXNzZnVsbHkgY2FuY2VsZWQiIH0=" } } } } ``` ## See also * [Create a session](/point-of-sale/shopper-engagement/create-session) * [Use terminal button to scan barcodes](/point-of-sale/android-terminals/scan-barcode/button-scan) * [Multiple barcode scans with Terminal API](/point-of-sale/android-terminals/scan-barcode/batch-session)