# Create a POS payment

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

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

## Credentials

- Request body field `seller_payme_id` (required): The seller's MPL.
- Request body field `payme_client_key` (optional): Partners only: your partner key. You can send it in the `PayMe-Partner-Key` header instead.

## Overview

Creates a sale and sends it to a paired POS device, then waits for the buyer to pay on the device. The result comes back in the same response; there is nothing to poll. To refund, see [Refund a POS sale](/payments/point-of-sale-pos/put-sales).

A declined or canceled payment returns **HTTP 200** with `status_code` `1`, `status_error_code` and `status_error_details`. Always check `status_code`, not the HTTP status. For example:

```json
{
  "status_code": 1,
  "payme_status": "error",
  "status_error_code": 20003,
  "status_error_details": "Transaction declined",
  "payme_sale_id": "SALE1700-000000AA-EXAMPLE1-SALE0001",
  "payme_sale_status": "failed"
}
```

- The seller must have an active POS service (error `720`), and the device must be paired and active.
- `sale_type` `sale` (default) charges the card; `authorize` only authorizes it. `token` returns error `357`.
- This call takes the same sale fields as [generate-sale](/payments/hosted-payment-page/post-generate-sale), for example `installments`.
- Setup, pairing and the two-step flow: [POS module overview](/payments/point-of-sale-pos).

## Authentication

Send `seller_payme_id` (the seller's MPL) in the JSON body. Partners also send `payme_client_key`, in the body or the `PayMe-Partner-Key` header.

## Errors

| HTTP | Code | When |
|---|---|---|
| 200 | Decline code | The payment was declined or canceled on the device. `status_code` is `1`. |
| 500 | `1` | A required field is missing, for example `seller_payme_id` or `currency`. `status_additional_info` names it. |
| 400 | `357` | `sale_type` `token` isn't supported here. |
| 400 | `720` | The POS service isn't active for this seller. |
| 400 | `26014` | `payment.pos_id` is missing, or the seller has no device with this ID. |
| 400 | `26017` | The device has no POS record. |
| 400 | `26018` | The device isn't active. |
| 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 |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | The seller's MPL. |
| `payme_client_key` | string | no | Partners only: your partner key. You can send it in the `PayMe-Partner-Key` header instead. |
| `sale_price` | integer | yes | Amount in minor units (`10000` = 100.00). |
| `currency` | string | yes | ISO 4217 currency code, for example `ILS`. |
| `product_name` | string | yes | What the buyer is paying for. |
| `payment` | object | yes | Where to send the payment. |
| `payment.method` | string | yes | `pos`. |
| `payment.pos_id` | string | yes | The device's ID, from the seller's POS service. The `point-of-sale-action-pair-update` callback also returns it. |
| `sale_type` | string | no | `sale` (default) charges the card. `authorize` only authorizes it. `token` returns error `357`. |
| `installments` | integer | no | Number of installments. |
| `transaction_id` | string | no | Your own reference for the sale. |
| `sale_callback_url` | string | no | URL for sale callbacks. Default: your partner's default callback URL, if one is set. |
| `customer` | object | no | Buyer details. Every field is optional. |
| `customer.name` | string | no | Buyer's name. |
| `customer.email` | string | no | Buyer's email. |
| `customer.phone` | string | no | Buyer's mobile number. |
| `customer.social_id` | string | no | Buyer's national ID. |
| `customer.zip_code` | string | no | Zip code. |
| `customer.country` | string | no | Two-letter ISO country code. |
| `customer.state` | string | no | State or region. |
| `customer.city` | string | no | City. |
| `customer.line1` | string | no | Address line 1. |
| `customer.line2` | string | no | Address line 2. |
| `customer.business_name` | string | no | The buyer's business name. Send it together with `business_code`. |
| `customer.business_code` | string | no | The buyer's business registration number. |
| `language` | string | no | Language of messages: `he` (default), `en`, `es`, `ru` or `ar`. |

### Request example

```json
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_price": 10000,
  "currency": "ILS",
  "product_name": "Coffee beans 1kg",
  "transaction_id": "order-1001",
  "sale_callback_url": "https://www.example.com/payment/callback",
  "payment": {
    "method": "pos",
    "pos_id": "001"
  },
  "customer": {
    "name": "Israel Israeli",
    "email": "buyer@example.com",
    "phone": "0500000000"
  },
  "language": "en"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/sales' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_price": 10000,
  "currency": "ILS",
  "product_name": "Coffee beans 1kg",
  "transaction_id": "order-1001",
  "sale_callback_url": "https://www.example.com/payment/callback",
  "payment": {
    "method": "pos",
    "pos_id": "001"
  },
  "customer": {
    "name": "Israel Israeli",
    "email": "buyer@example.com",
    "phone": "0500000000"
  },
  "language": "en"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/sales", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "sale_price": 10000,
    "currency": "ILS",
    "product_name": "Coffee beans 1kg",
    "transaction_id": "order-1001",
    "sale_callback_url": "https://www.example.com/payment/callback",
    "payment": {
      "method": "pos",
      "pos_id": "001"
    },
    "customer": {
      "name": "Israel Israeli",
      "email": "buyer@example.com",
      "phone": "0500000000"
    },
    "language": "en"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/sales",
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "sale_price": 10000,
        "currency": "ILS",
        "product_name": "Coffee beans 1kg",
        "transaction_id": "order-1001",
        "sale_callback_url": "https://www.example.com/payment/callback",
        "payment": {
            "method": "pos",
            "pos_id": "001",
        },
        "customer": {
            "name": "Israel Israeli",
            "email": "buyer@example.com",
            "phone": "0500000000",
        },
        "language": "en",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_price": 10000,
  "currency": "ILS",
  "product_name": "Coffee beans 1kg",
  "transaction_id": "order-1001",
  "sale_callback_url": "https://www.example.com/payment/callback",
  "payment": {
    "method": "pos",
    "pos_id": "001"
  },
  "customer": {
    "name": "Israel Israeli",
    "email": "buyer@example.com",
    "phone": "0500000000"
  },
  "language": "en"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/sales');
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 returned a result: paid (`status_code` `0`) or declined (`status_code` `1`). (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` paid. `1` declined or canceled (still HTTP 200). |
| `payme_status` | string | `success`, or `error` when the payment failed. |
| `status_error_code` | integer | `0` on success; otherwise the decline code. |
| `status_error_details` | string | Why the payment failed, when `status_code` is `1`. |
| `payme_sale_id` | string | PayMe's sale ID. Use it to refund. |
| `payme_sale_code` | integer | PayMe's numeric sale ID. |
| `sale_created` | string | When the sale was created. |
| `payme_sale_status` | string | Sale status, for example `completed`. See [Sale statuses](/payments/codes-statuses/sale-statuses). |
| `sale_status` | string | Same as `payme_sale_status`. |
| `currency` | string | ISO 4217 currency code. |
| `transaction_id` | string | Your reference, as sent. |
| `is_token_sale` | boolean | `true` if the sale was paid with a saved token. |
| `price` | integer | Sale amount in minor units. |
| `payme_signature` | string | Signature of the sale. See [Callbacks](/payments/getting-started/callbacks). |
| `sale_description` | string | The `product_name` you sent. |
| `sale_deferred_months` | integer | Deferred months, or `null`. |
| `payme_transaction_id` | string | PayMe's transaction ID. |
| `payme_transaction_total` | string | Amount charged, in minor units. |
| `payme_transaction_card_brand` | string | Card brand. |
| `payme_transaction_auth_number` | string | Authorization number. |
| `payme_transaction_voucher` | string | Voucher number, or `null`. |
| `payme_transaction_emv_uid` | string | EMV transaction ID from the device. |
| `payme_transaction_acquirer` | string | The acquirer. |
| `payme_transaction_auth_source` | string | Who authorized the transaction, for example `CreditCompany`. |
| `payme_transaction_card_issuer` | string | The card issuer. |
| `payme_transaction_credit_type` | string | Credit type, for example `RegularCredit`. |
| `buyer_name` | string | Buyer's name. |
| `buyer_email` | string | Buyer's email. |
| `buyer_phone` | string | Buyer's phone number. |
| `buyer_card_mask` | string | Masked card number. |
| `buyer_card_exp` | string | Card expiry, `MMYY`. |
| `buyer_card_is_foreign` | boolean | `true` if the card was issued outside the seller's country. |
| `buyer_social_id` | string | Buyer's national ID, or `null`. |
| `installments` | integer | Number of installments. |
| `transaction_first_payment` | string | First installment amount, in minor units. |
| `transaction_periodical_payment` | integer | Amount of each later installment, in minor units. `0` for a single payment. |
| `transaction_arn` | string | Acquirer reference number (ARN). |
| `sale_paid_date` | string | When the sale was paid. |
| `sale_release_date` | string | When the funds are released to the seller, or `null`. |
| `sale_3ds` | boolean | `true` if 3D Secure was used. |
| `redirect_url` | string | The sale's return URL, or `null`. |

```json
{
  "status_code": 0,
  "payme_status": "success",
  "status_error_code": 0,
  "payme_sale_id": "SALE1700-000000AA-EXAMPLE1-SALE0001",
  "payme_sale_code": 12346578,
  "sale_created": "2026-11-09 13:33:54",
  "payme_sale_status": "completed",
  "sale_status": "completed",
  "currency": "ILS",
  "transaction_id": "order-1001",
  "is_token_sale": false,
  "price": 10000,
  "payme_signature": "db1c276**********c5b39",
  "sale_description": "Coffee beans 1kg",
  "sale_deferred_months": null,
  "payme_transaction_id": "TRAN1688-034834SZ-OYNALKNE-DWOXFEUZ",
  "payme_transaction_total": "10000",
  "payme_transaction_card_brand": "Mastercard",
  "payme_transaction_auth_number": "12345678",
  "payme_transaction_voucher": null,
  "payme_transaction_emv_uid": "2306**********102613",
  "payme_transaction_acquirer": "PayMe",
  "payme_transaction_auth_source": "CreditCompany",
  "payme_transaction_card_issuer": "Isracard",
  "payme_transaction_credit_type": "RegularCredit",
  "buyer_name": "Israel Israeli",
  "buyer_email": "buyer@example.com",
  "buyer_phone": "0500000000",
  "buyer_card_mask": "532610******5846",
  "buyer_card_exp": "0426",
  "buyer_card_is_foreign": false,
  "buyer_social_id": null,
  "installments": 1,
  "transaction_first_payment": "10000",
  "transaction_periodical_payment": 0,
  "transaction_arn": "2306**********2613",
  "sale_paid_date": "2026-11-09 13:34:20",
  "sale_release_date": null,
  "sale_3ds": false,
  "redirect_url": null
}
```

### 400 — The device or the POS service can't take the payment. 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": "Desired device is inactive",
  "status_additional_info": null,
  "status_error_code": 26018,
  "session": "FhT3aXe7"
}
```

### 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": "Required parameter is missing",
  "status_additional_info": "currency",
  "status_error_code": 1,
  "session": "FhT3aXe7"
}
```