# Authenticate a POS device Building with an AI agent? Start at https://docs.payme.io/agents.md - Sandbox: `POST https://sandbox.payme.io/api/pos/authenticate` - Production: `POST https://live.payme.io/api/pos/authenticate` ## Credentials - Request body field `payme_client_key` (required): Your partner key. Send it in the JSON body: this call doesn't read the `PayMe-Partner-Key` header. - Request body field `seller_payme_id` (required): The MPL of the seller that owns the device. Send it in the JSON body. ## Overview Completes the pairing of a device that [Pair a POS device](/payments/point-of-sale-pos/post-pos-pair) registered, with the device's 6-digit verification code. On success, the device becomes active and can take payments, and PayMe sends the `point-of-sale-action-authenticate-update` seller callback to your partner callback URL, with `pos_id` and `pos_name` (see [Callbacks](/payments/getting-started/callbacks)). Send `verification_code` as a string, so that a leading zero is kept: PayMe checks that it is a number and that it is exactly 6 characters long. Example: `POST https://sandbox.payme.io/api/pos/authenticate`. When the service that runs the devices refuses the request, or can't be reached, the response is HTTP 200 with `status_code` `1`: ```json { "status_code": 1, "session": "Ab12Cd34", "status_error_code": 20002, "status_error_details": "The message of the service that runs the devices" } ``` Check `status_code`, not only the HTTP status. ## Authentication Partners only. Send your partner key as `payme_client_key` and the seller's MPL as `seller_payme_id`, both in the JSON body; a header doesn't replace either of them. The seller must have an active POS service that lists the device's `pos_id`. This call doesn't read `language`: error messages come back in PayMe's default language (Hebrew). ## Errors | HTTP | Code | When | |---|---|---| | 500 | `900` | The body isn't JSON: send `Content-Type: application/json`. | | 500 | `901` | The JSON body is empty or invalid. | | 500 | `1` | A required field is missing: `payme_client_key`, `seller_payme_id`, `pos_id`, `terminal_id` or `verification_code`. `status_additional_info` names it. | | 400 | `20` | `seller_payme_id` has characters other than letters, digits, `-` and `_`. | | 500 | `200` | The partner key is unknown. | | 500 | `201` | The partner isn't active. | | 500 | `251` | The seller key is unknown. | | 500 | `163` | The seller isn't active. | | 400 | `720` | The seller has no active POS service. `status_additional_info` is `pos`. | | 400 | `26014` | None of the seller's POS services lists this `pos_id`. `status_additional_info` is `pos`. | | 500 | `10` | `verification_code` isn't a number, or is negative. | | 500 | `999` | `verification_code` isn't exactly 6 digits. `status_error_details` is `verification_code should be 6 digits`. | | 400 | `26017` | The device was never paired: call [Pair a POS device](/payments/point-of-sale-pos/post-pos-pair) first. | | 200 | `20002` | The service that runs the devices refused the request or couldn't be reached. `status_code` is `1`, and `status_error_details` holds that service's message. | ## Parameters This endpoint takes no path, query or header parameters. ## Request body Content type: `application/json` All fields in the JSON body. | Field | Type | Required | Description | | --- | --- | --- | --- | | `payme_client_key` | string | yes | Your partner key. Send it in the JSON body: this call doesn't read the `PayMe-Partner-Key` header. | | `seller_payme_id` | string | yes | The MPL of the seller that owns the device. Send it in the JSON body. | | `pos_id` | string | yes | The device's ID, as listed in the seller's POS service: the `pos_id` you sent to [Order POS devices](/payments/point-of-sale-pos/post-vas-enable). Another value returns `26014`. | | `terminal_id` | string | yes | The device's payment terminal ID. | | `verification_code` | string | yes | The 6-digit verification code for this pairing, as a string so that a leading zero is kept. | ### Request example ```json { "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "pos_id": "001", "terminal_id": "0882001", "verification_code": "048213" } ``` ## Code samples ### curl ```bash curl -X POST 'https://sandbox.payme.io/api/pos/authenticate' \ -H 'Content-Type: application/json' \ --data-raw '{ "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "pos_id": "001", "terminal_id": "0882001", "verification_code": "048213" }' ``` ### Node.js ```javascript const response = await fetch("https://sandbox.payme.io/api/pos/authenticate", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "pos_id": "001", "terminal_id": "0882001", "verification_code": "048213" }), }); console.log(await response.text()); ``` ### Python ```python import requests response = requests.post( "https://sandbox.payme.io/api/pos/authenticate", json={ "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "pos_id": "001", "terminal_id": "0882001", "verification_code": "048213", }, ) print(response.text) ``` ### PHP ```php 'POST', CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => $body, ]); $response = curl_exec($ch); curl_close($ch); echo $response; ``` ## Responses ### 200 — The device is active (`status_code` `0`), or the service that runs the devices refused the request (`status_code` `1`, `20002`). (success) | Field | Type | Description | | --- | --- | --- | | `status_code` | integer | `0` on success; `1` when the service that runs the devices refused the request (`20002`). | | `session` | string | PayMe session ID. Quote it when you contact PayMe support. | | `status_error_code` | integer | `20002`. Only when `status_code` is `1`. | | `status_error_details` | string | The message of the service that runs the devices. Only when `status_code` is `1`. | ```json { "status_code": 0, "session": "Ab12Cd34" } ``` ### 400 — The seller has no active POS service, the device isn't in it, or the device was never paired. See the error table above. (error) | Field | Type | Description | | --- | --- | --- | | `status_code` | integer | `1` on failure. | | `status_error_details` | string | The error message. | | `status_additional_info` | string | The field or value concerned. Can be `null`. | | `status_error_code` | integer | PayMe error code. See the error table above. | | `session` | string | PayMe session ID. Quote it when you contact PayMe support. | ```json { "status_code": 1, "status_error_details": "נקודת המכירה לא נמצאה", "status_additional_info": "pos", "status_error_code": 26014, "session": "Ab12Cd34" } ``` ### 500 — The request or its credentials were refused. See the error table above. (error) | Field | Type | Description | | --- | --- | --- | | `status_code` | integer | `1` on failure. | | `status_error_details` | string | The error message. | | `status_additional_info` | string | The field or value concerned. Can be `null`. | | `status_error_code` | integer | PayMe error code. See the error table above. | | `session` | string | PayMe session ID. Quote it when you contact PayMe support. | ```json { "status_code": 1, "status_error_details": "verification_code should be 6 digits", "status_additional_info": null, "status_error_code": 999, "session": "Ab12Cd34" } ```