# Order POS devices

Building with an AI agent? Start at https://docs.payme.io/agents.md

- Sandbox: `POST https://sandbox.payme.io/api/vas-enable`
- Production: `POST https://live.payme.io/api/vas-enable`

## Credentials

- Request body field `payme_client_key` (required): Your partner key.
- Request body field `seller_payme_id` (required): The seller's MPL.

## Overview

Partners only. Orders POS devices for a seller by enabling the POS services with `vas-enable`. The process is manual: PayMe requests a new terminal (up to 5 business days), prepares the devices and ships them. PayMe pairs each device and sends you a `point-of-sale-action-pair-update` callback with its `pos_id`.

Depending on how the service is set up, PayMe either opens a support ticket for the order (response `status_code` `2`, `Zendesk ticket created`) or enables the service at once and returns its details.

### Step 1: enable the POS payment method

Call `vas-enable` with the `vas_payme_id` of the POS payment method service.

```json
{
  "payme_client_key": "<your partner key>",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "vas_payme_id": "VASL1545-8192915E-8192915E-8192915E"
}
```

### Step 2: order the devices

Call `vas-enable` with the `vas_payme_id` of the POS device service and the device list in `vas_data`.

```json
{
  "payme_client_key": "<your partner key>",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
  "vas_data": {
    "number_of_devices": 2,
    "items": [
      {
        "pos_id": "001",
        "shipping_address": "1 Example St, Tel Aviv",
        "name": "Front counter"
      },
      {
        "pos_id": "002",
        "shipping_address": "1 Example St, Tel Aviv",
        "name": "Back counter"
      }
    ]
  }
}
```

### Adding devices later

Call step 2 again with only the new devices and `vas_data.extend_items` `true`. Without `extend_items`, the list you send replaces the devices already stored.

```json
{
  "payme_client_key": "<your partner key>",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
  "vas_data": {
    "extend_items": true,
    "number_of_devices": 1,
    "items": [
      {
        "pos_id": "003",
        "shipping_address": "1 Example St, Tel Aviv",
        "name": "Terrace"
      }
    ]
  }
}
```

## Errors

Errors return `status_code` `1`.

| HTTP | Code | When |
|---|---|---|
| 500 | `1` | `payme_client_key`, `seller_payme_id` or `vas_payme_id` is missing. |
| 400 | `703` | Your partner account has no permission for this service (`Partner has no permission for this VAS`). |
| 500 | `720` | No service has this `vas_payme_id`. |
| 500 | `200` | The partner key is unknown. |
| 500 | `251` | The seller key is unknown. |

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | yes | Your partner key. |
| `seller_payme_id` | string | yes | The seller's MPL. |
| `vas_payme_id` | string | yes | The service to enable: the POS payment method service (step 1) or the POS device service (step 2). |
| `vas_payer_type` | integer | no | Who pays the service fees: `1` partner, `2` seller, `3` reseller. Used only when the service is first created for the seller. Default: the payer set on your partner's service. |
| `vas_data` | object | no | The device order. Send it in step 2. |
| `vas_data.number_of_devices` | integer | yes | Number of devices ordered. It must equal the number of `items`. |
| `vas_data.items` | array | yes | One entry per device. |
| `vas_data.items[].pos_id` | string | yes | The device's POS ID. Payment requests address the device by this ID (`payment.pos_id`). |
| `vas_data.items[].shipping_address` | string | yes | Where to ship the device. |
| `vas_data.items[].name` | string | yes | A name for the device, used during setup. |
| `vas_data.extend_items` | boolean | no | `true` adds `items` to the devices already ordered for this seller. Default: the list you send replaces them. |

### Request example

```json
{
  "payme_client_key": "<your partner key>",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
  "vas_data": {
    "number_of_devices": 2,
    "items": [
      {
        "pos_id": "001",
        "shipping_address": "1 Example St, Tel Aviv",
        "name": "Front counter"
      },
      {
        "pos_id": "002",
        "shipping_address": "1 Example St, Tel Aviv",
        "name": "Back counter"
      }
    ]
  }
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/vas-enable' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "payme_client_key": "<your partner key>",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
  "vas_data": {
    "number_of_devices": 2,
    "items": [
      {
        "pos_id": "001",
        "shipping_address": "1 Example St, Tel Aviv",
        "name": "Front counter"
      },
      {
        "pos_id": "002",
        "shipping_address": "1 Example St, Tel Aviv",
        "name": "Back counter"
      }
    ]
  }
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/vas-enable", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "payme_client_key": "<your partner key>",
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
    "vas_data": {
      "number_of_devices": 2,
      "items": [
        {
          "pos_id": "001",
          "shipping_address": "1 Example St, Tel Aviv",
          "name": "Front counter"
        },
        {
          "pos_id": "002",
          "shipping_address": "1 Example St, Tel Aviv",
          "name": "Back counter"
        }
      ]
    }
  }),
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/vas-enable",
    json={
        "payme_client_key": "<your partner key>",
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
        "vas_data": {
            "number_of_devices": 2,
            "items": [
                {
                    "pos_id": "001",
                    "shipping_address": "1 Example St, Tel Aviv",
                    "name": "Front counter",
                },
                {
                    "pos_id": "002",
                    "shipping_address": "1 Example St, Tel Aviv",
                    "name": "Back counter",
                },
            ],
        },
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "payme_client_key": "<your partner key>",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "vas_payme_id": "VASL1545-8192915E-5NTSEUM1-03YNFWNU",
  "vas_data": {
    "number_of_devices": 2,
    "items": [
      {
        "pos_id": "001",
        "shipping_address": "1 Example St, Tel Aviv",
        "name": "Front counter"
      },
      {
        "pos_id": "002",
        "shipping_address": "1 Example St, Tel Aviv",
        "name": "Back counter"
      }
    ]
  }
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/vas-enable');
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 — PayMe opened a ticket for the order (`status_code` `2`), or enabled the service (`status_code` `0`). (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `2` PayMe opened a support ticket for the order. `0` the service was enabled; the service fields below are returned. |
| `seller_payme_id` | string | The seller's MPL. |
| `message` | string | `Zendesk ticket created`, when `status_code` is `2`. |
| `vas_payme_id` | string | The `vas_payme_id` you sent, when `status_code` is `0`. |
| `vas_guid` | string | ID of the seller's service, when `status_code` is `0`. |
| `vas_is_active` | boolean | `true` if the seller's service is active. |
| `vas_type` | string | Service type. |
| `vas_description` | string | Service description. |
| `vas_payer_type` | integer | Who pays the service fees: `1` partner, `2` seller, `3` reseller. |
| `vas_data` | object | The stored device list, without hidden fields. |

```json
{
  "status_code": 2,
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "message": "Zendesk ticket created"
}
```

### 500 — The request was refused. See the error table. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | What went wrong, in the language you asked for (Hebrew by default). |
| `status_additional_info` | string | The field or value concerned. Can be `null`. |
| `status_error_code` | integer | PayMe error code. See the error table above and [Errors](/payments/getting-started/errors). |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```