# Pair a POS device Building with an AI agent? Start at https://docs.payme.io/agents.md - Sandbox: `POST https://sandbox.payme.io/api/pos/pair` - Production: `POST https://live.payme.io/api/pos/pair` ## 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 Registers a POS device for a seller with the service that runs the devices. PayMe pairs new devices itself before they ship (see [Order POS devices](/payments/point-of-sale-pos/post-vas-enable)); use this call to pair a device from your own system. On success, PayMe records the device as paired but not active and sends the `point-of-sale-action-pair-update` seller callback to your partner callback URL, with `pos_id` and `pos_name` (see [Callbacks](/payments/getting-started/callbacks)). Then call [Authenticate a POS device](/payments/point-of-sale-pos/post-pos-authenticate). The device takes payments only after both steps. Pairing a device that is already active makes it inactive until you authenticate it again. Example: `POST https://sandbox.payme.io/api/pos/pair`. 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` or `terminal_id`. `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`. | | 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. | | `name` | string | no | A name for the device. Default: the seller's business name. The callbacks return it as `pos_name`. | ### Request example ```json { "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "pos_id": "001", "terminal_id": "0882001", "name": "Front counter" } ``` ## Code samples ### curl ```bash curl -X POST 'https://sandbox.payme.io/api/pos/pair' \ -H 'Content-Type: application/json' \ --data-raw '{ "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "pos_id": "001", "terminal_id": "0882001", "name": "Front counter" }' ``` ### Node.js ```javascript const response = await fetch("https://sandbox.payme.io/api/pos/pair", { 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", "name": "Front counter" }), }); console.log(await response.text()); ``` ### Python ```python import requests response = requests.post( "https://sandbox.payme.io/api/pos/pair", json={ "payme_client_key": "XXXXXXXX", "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "pos_id": "001", "terminal_id": "0882001", "name": "Front counter", }, ) 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 was paired (`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, or the device isn't in it. 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": "Required parameter is missing", "status_additional_info": "terminal_id", "status_error_code": 1, "session": "Ab12Cd34" } ```