Authenticate a POS device

Credentials

Overview

Completes the pairing of a device that Pair a POS device 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).

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:

{
  "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 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. 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

{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "pos_id": "001",
  "terminal_id": "0882001",
  "verification_code": "048213"
}

Code samples

curl

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

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

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

$body = <<<'BODY'
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "pos_id": "001",
  "terminal_id": "0882001",
  "verification_code": "048213"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/pos/authenticate');
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 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.
{
  "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.
{
  "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": "verification_code should be 6 digits",
  "status_additional_info": null,
  "status_error_code": 999,
  "session": "Ab12Cd34"
}