Pair a POS device
- 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 thePayMe-Partner-Keyheader. - 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); 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). Then call Authenticate a POS device. 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:
{
"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. 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
{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"pos_id": "001",
"terminal_id": "0882001",
"name": "Front counter"
}
Code samples
curl
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
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
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
$body = <<<'BODY'
{
"payme_client_key": "XXXXXXXX",
"seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
"pos_id": "001",
"terminal_id": "0882001",
"name": "Front counter"
}
BODY;
$ch = curl_init('https://sandbox.payme.io/api/pos/pair');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => '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. |
{
"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. |
{
"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. |
{
"status_code": 1,
"status_error_details": "Required parameter is missing",
"status_additional_info": "terminal_id",
"status_error_code": 1,
"session": "Ab12Cd34"
}