Pair a POS device

Credentials

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"
}