# Create a document

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

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

## Credentials

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

> ⚠️ **This API is deprecated** and is no longer recommended for use. For questions, contact partners@payme.io. 

## Overview

Creates an invoice, receipt or other tax document for the seller through PayMe's invoicing service. The seller's invoicing service must be active; otherwise every documents call returns error `703` (HTTP 403).

Documents are created asynchronously: the response returns `doc_id` and `doc_url` at once, but the document may not be ready yet. While the document job is still running (its status is `waiting`, `active`, `delayed`, `paused` or `stuck`), [Get a document](/payments/invoices/show-generated-document-by-id) returns error `1005` with HTTP 400 and the status in `status_additional_info`, for example `status:waiting`. Wait a few seconds and call it again.

If the seller still has to approve the connection to the Israel Tax Authority, the response holds only `authority_redirect_url` and no document is created. Send the seller to that URL to approve it, then call again.

PayMe passes amounts, totals and `vat_rate` to the invoicing service as you send them. Don't send card numbers or CVVs: a document needs no card data.

#### Document types
The types you can create are listed on [Document types](/payments/codes-statuses/document-types).

#### Documents issued automatically
With the invoicing service active on the account, a paid sale issues a document and a refund (including a refund of a subscription charge) automatically issues a credit document. A refund never un-issues the original document; canceling a document takes a separate counter-document. To skip the automatic document for one API sale, send `"services": [{"name": "invoice", "settings": {"active": false}}]` on `generate-sale`. 

## Authentication

Name the seller with `seller_payme_id` in the body or the `PayMe-Merchant-Key` header. A partner may instead send `payme_client_key` (body or `PayMe-Partner-Key` header) with its own `seller_id`. With no credential at all, the call returns error `1` with `status_additional_info` `payme_client_key`.

### Errors

| HTTP | Code | When |
|---|---|---|
| `400` | `20` | Validation failed. `status_additional_info` lists the messages per field. |
| `400` | `1` | A partner key was sent, but no seller. `status_additional_info` is `seller_payme_id`.  |
| `400` | `20` | The seller doesn't belong to this partner. `status_additional_info` is `Merchant-Seller inconsistency`.  |
| `403` | `703` | The invoicing service isn't active for this seller.  |
| `500` | `1` | No credential was sent at all. `status_additional_info` is `payme_client_key`.  |
| `500` | `251` | The seller key is unknown.  |
| `500` | `163` | The seller isn't active.  |
| `500` | `200` | The partner key is unknown.  |
| `500` | `201` | The partner isn't active.  |
| `500` | `1001` | The invoicing service returned an error. `status_additional_info` carries its code and details. |
| `503` | `1001` | The invoicing service didn't answer in time. |
| `500` | `1004` | The invoicing service didn't create the document. |

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | no | The seller's MPL, instead of `seller_payme_id` in the body. |

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | The seller's MPL. You can send it in the `PayMe-Merchant-Key` header instead. |
| `payme_client_key` | string | no | Partners only: your partner key, in the body or the `PayMe-Partner-Key` header. |
| `seller_id` | string | no | Partners only: your own reference for the seller, instead of `seller_payme_id`. Needs `payme_client_key`. |
| `doc_type` | integer | yes | Document type: `100`, `200`, `300`, `305`, `320`, `330`, `400`, `405` or `600`. See [Document types](/payments/codes-statuses/document-types). |
| `buyer_name` | string | yes | Buyer name printed on the document. |
| `buyer_address` | string | no | Buyer address printed on the document. |
| `buyer_social_id` | string | no | Buyer national ID or company number, printed as the buyer's tax ID. Default: `credit_card.buyer_social_id`. |
| `currency` | string | no | ISO 4217 currency code of the document. |
| `language` | string | no | Document language: `he` (default) or `en`. |
| `doc_date` | string | no | Document date, for example `2026-11-09`. |
| `due_date` | string | no | Payment due date. |
| `pay_date` | string | no | Date the payment was made. |
| `doc_title` | string | no | Title printed at the top of the document. |
| `doc_comments` | string | no | Comments printed on the document. |
| `exchange_rate` | number | no | Exchange rate used on the document. |
| `vat_rate` | number | no | VAT rate applied to the document. |
| `discount` | number | no | Discount applied to the document. |
| `total_excluding_vat` | number | no | Total before VAT. |
| `total_sum_after_discount` | number | no | Total after the discount. |
| `total_sum_including_vat` | number | no | Total including VAT. |
| `total_vat` | number | no | Total VAT. |
| `total_paid` | number | no | Total paid on this document. |
| `total_paid_including_vat` | number | no | Total paid, including VAT. |
| `items` | array | yes | Document lines. At least one. |
| `items[].description` | string | yes | Line description, at least 3 characters. |
| `items[].unit_price` | number | no | Unit price before VAT. Send `unit_price` or `unit_price_with_vat`. |
| `items[].unit_price_with_vat` | number | no | Unit price including VAT. |
| `items[].quantity` | integer | no | Quantity. |
| `items[].vat_exempt` | boolean | no | `true` if the line is exempt from VAT. |
| `items[].currency` | string | no | ISO 4217 currency code of the line. |
| `items[].exchange_rate` | number | no | Exchange rate of the line's currency. |
| `cash` | object | no | Cash payment received. Send it only for cash that was actually paid. |
| `cash.sum` | number | yes | Amount paid in cash. |
| `cheques` | array | no | Cheques received. |
| `cheques[].sum` | number | yes | Cheque amount. |
| `cheques[].date` | string | yes | Cheque date. |
| `cheques[].bank` | number | no | Bank code. See [Banks in Israel](/payments/codes-statuses/banks-in-israel). |
| `cheques[].branch` | number | no | Branch number. |
| `cheques[].account` | string | no | Account number, digits only. |
| `cheques[].number` | string | no | Cheque number, digits only. |
| `bank_transfer` | object | no | Bank transfer received. Send it only for a transfer that was actually made. |
| `bank_transfer.sum` | number | yes | Amount transferred. |
| `bank_transfer.date` | string | no | Date the transfer was received. |
| `bank_transfer.account` | string | no | Account number, digits only. |
| `paypal` | object | no | PayPal payment received. |
| `paypal.sum` | number | yes | Amount paid with PayPal. |
| `paypal.date` | string | yes | Payment date. |
| `paypal.transaction_id` | string | yes | PayPal transaction ID. |
| `paypal.buyer_name` | string | yes | Payer name. |
| `credit_card` | object | no | Card payment received. Don't send the card number or CVV. |
| `credit_card.sum` | number | yes | Amount paid by card. |
| `credit_card.date` | string | no | Payment date. |
| `credit_card.installments` | integer | no | Number of installments. |
| `credit_card.first_payment` | number | no | Amount of the first installment. |
| `credit_card.type` | string | no | Card brand, for example `Visa`. |
| `credit_card.expiry` | string | no | Card expiry, exactly 4 characters `MMYY`. Must not be in the past. |
| `credit_card.buyer_name` | string | no | Card holder's name. |
| `credit_card.buyer_social_id` | string | no | Card holder's national ID, digits only. Also printed as the buyer's tax ID when `buyer_social_id` isn't sent. |
| `credit_card.auth_number` | string | no | Authorization number of the card payment. |

### Request example

```json
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "doc_type": 400,
  "buyer_name": "Israel Israeli",
  "doc_date": "2026-11-09",
  "currency": "ILS",
  "language": "he",
  "doc_title": "Receipt for order 1001",
  "total_paid": 140,
  "items": [
    {
      "description": "Monthly plan",
      "quantity": 1,
      "unit_price": 140,
      "vat_exempt": false,
      "currency": "ILS"
    }
  ],
  "cash": {
    "sum": 40
  },
  "credit_card": {
    "sum": 100,
    "installments": 1,
    "type": "Visa",
    "expiry": "1230",
    "buyer_name": "Israel Israeli",
    "auth_number": "0123456"
  }
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/documents' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  --data-raw '{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "doc_type": 400,
  "buyer_name": "Israel Israeli",
  "doc_date": "2026-11-09",
  "currency": "ILS",
  "language": "he",
  "doc_title": "Receipt for order 1001",
  "total_paid": 140,
  "items": [
    {
      "description": "Monthly plan",
      "quantity": 1,
      "unit_price": 140,
      "vat_exempt": false,
      "currency": "ILS"
    }
  ],
  "cash": {
    "sum": 40
  },
  "credit_card": {
    "sum": 100,
    "installments": 1,
    "type": "Visa",
    "expiry": "1230",
    "buyer_name": "Israel Israeli",
    "auth_number": "0123456"
  }
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/documents", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
  body: JSON.stringify({
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "doc_type": 400,
    "buyer_name": "Israel Israeli",
    "doc_date": "2026-11-09",
    "currency": "ILS",
    "language": "he",
    "doc_title": "Receipt for order 1001",
    "total_paid": 140,
    "items": [
      {
        "description": "Monthly plan",
        "quantity": 1,
        "unit_price": 140,
        "vat_exempt": false,
        "currency": "ILS"
      }
    ],
    "cash": {
      "sum": 40
    },
    "credit_card": {
      "sum": 100,
      "installments": 1,
      "type": "Visa",
      "expiry": "1230",
      "buyer_name": "Israel Israeli",
      "auth_number": "0123456"
    }
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/documents",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "doc_type": 400,
        "buyer_name": "Israel Israeli",
        "doc_date": "2026-11-09",
        "currency": "ILS",
        "language": "he",
        "doc_title": "Receipt for order 1001",
        "total_paid": 140,
        "items": [
            {
                "description": "Monthly plan",
                "quantity": 1,
                "unit_price": 140,
                "vat_exempt": False,
                "currency": "ILS",
            },
        ],
        "cash": {
            "sum": 40,
        },
        "credit_card": {
            "sum": 100,
            "installments": 1,
            "type": "Visa",
            "expiry": "1230",
            "buyer_name": "Israel Israeli",
            "auth_number": "0123456",
        },
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "doc_type": 400,
  "buyer_name": "Israel Israeli",
  "doc_date": "2026-11-09",
  "currency": "ILS",
  "language": "he",
  "doc_title": "Receipt for order 1001",
  "total_paid": 140,
  "items": [
    {
      "description": "Monthly plan",
      "quantity": 1,
      "unit_price": 140,
      "vat_exempt": false,
      "currency": "ILS"
    }
  ],
  "cash": {
    "sum": 40
  },
  "credit_card": {
    "sum": 100,
    "installments": 1,
    "type": "Visa",
    "expiry": "1230",
    "buyer_name": "Israel Israeli",
    "auth_number": "0123456"
  }
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/documents');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 200 — The document job was created. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `doc_id` | string | The document's job ID. Use it with [Get a document](/payments/invoices/show-generated-document-by-id). |
| `doc_num` | string | The document number, once the invoicing service has assigned one. |
| `doc_status` | string | Status of the document job, when the invoicing service returns one. |
| `doc_url` | string | Link to the document. |
| `doc_type` | integer | Document type. See [Document types](/payments/codes-statuses/document-types). |
| `buyer_name` | string | Buyer name on the document. |
| `buyer_address` | string | Buyer address on the document, if sent. |
| `doc_date` | string | Document date. |
| `due_date` | string | Payment due date, if sent. |
| `pay_date` | string | Payment date, if sent. |
| `currency` | string | ISO 4217 currency code of the document. |
| `language` | string | Document language. |
| `doc_title` | string | Title printed at the top of the document. |
| `doc_comments` | string | Comments printed on the document. |
| `exchange_rate` | number | Exchange rate used on the document. |
| `vat_rate` | number | VAT rate applied to the document. |
| `discount` | number | Discount applied to the document. |
| `total_excluding_vat` | number | Total before VAT. |
| `total_sum_after_discount` | number | Total after the discount. |
| `total_sum_including_vat` | number | Total including VAT. |
| `total_vat` | number | Total VAT. |
| `total_paid` | number | Total paid on this document. |
| `total_paid_including_vat` | number | Total paid, including VAT. |
| `items` | array | Document lines. |
| `items[].description` | string | Line description. |
| `items[].quantity` | integer | Quantity. |
| `items[].unit_price` | number | Unit price before VAT. |
| `items[].unit_price_with_vat` | number | Unit price including VAT. |
| `items[].vat_exempt` | boolean | `true` if the line is exempt from VAT. |
| `items[].currency` | string | ISO 4217 currency code of the line. |
| `items[].exchange_rate` | number | Exchange rate of the line's currency. |
| `cash` | object | Cash payment recorded on the document. |
| `cash.sum` | number | Amount paid in cash. |
| `cheques` | array | Cheques recorded on the document. |
| `cheques[].sum` | number | Cheque amount. |
| `cheques[].date` | string | Cheque date. |
| `cheques[].bank` | number | Bank code. |
| `cheques[].branch` | number | Branch number. |
| `cheques[].account` | string | Account number. |
| `cheques[].number` | string | Cheque number. |
| `bank_transfer` | object | Bank transfer recorded on the document. |
| `bank_transfer.sum` | number | Amount transferred. |
| `bank_transfer.date` | string | Transfer date. |
| `bank_transfer.account` | string | Account number. |
| `paypal` | object | PayPal payment recorded on the document. |
| `paypal.sum` | number | Amount paid with PayPal. |
| `paypal.date` | string | Payment date. |
| `paypal.transaction_id` | string | PayPal transaction ID. |
| `paypal.buyer_name` | string | Payer name. |
| `credit_card` | object | Card payment recorded on the document. It holds no card number or CVV. |
| `credit_card.sum` | number | Amount paid by card. |
| `credit_card.installments` | integer | Number of installments. |
| `credit_card.first_payment` | number | Amount of the first installment. |
| `credit_card.type` | string | Card brand. |
| `credit_card.expiry` | string | Card expiry, `MMYY`. |
| `credit_card.buyer_name` | string | Card holder's name. |
| `credit_card.buyer_social_id` | string | Card holder's national ID. |
| `credit_card.auth_number` | string | Authorization number of the card payment. |
| `authority_redirect_url` | string | Returned instead of the other fields when the seller must first approve the connection to the Israel Tax Authority. No document was created. |

```json
{
  "status_code": 0,
  "doc_id": "fa397fce-aee6-4c6d-ae9c-273ae1e3a317",
  "doc_type": 400,
  "buyer_name": "Israel Israeli",
  "doc_date": "2026-11-09",
  "currency": "ILS",
  "language": "he",
  "doc_title": "Receipt for order 1001",
  "total_paid": 140,
  "items": [
    {
      "description": "Monthly plan",
      "quantity": 1,
      "unit_price": 140,
      "vat_exempt": false,
      "currency": "ILS"
    }
  ],
  "cash": {
    "sum": 40
  },
  "credit_card": {
    "sum": 100,
    "installments": 1,
    "type": "Visa",
    "expiry": "1230",
    "buyer_name": "Israel Israeli",
    "auth_number": "0123456"
  },
  "doc_url": "https://invoice-staging.paymeservice.com/documents/fa397fce-aee6-4c6d-ae9c-273ae1e3a317"
}
```

### 400 — Validation failed (`20`), or a partner key came without a seller (`1`). (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | What went wrong. |
| `status_additional_info` | object | For a validation error, the messages per field, each an array of strings. Otherwise the field concerned, as a string. |
| `status_error_code` | integer | PayMe error code: `20` for a validation error. |
| `session` | string | PayMe session ID. Quote it when you contact support. |

```json
{
  "status_code": 1,
  "status_error_details": "The given data was invalid.",
  "status_additional_info": {
    "doc_type": [
      "The doc type field is required."
    ],
    "items": [
      "The items field is required."
    ],
    "buyer_name": [
      "The buyer name field is required."
    ]
  },
  "status_error_code": 20,
  "session": "FhT3aXe7"
}
```

### 403 — The invoicing service isn't active for this seller (`703`). (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": "Action is not permitted",
  "status_additional_info": "Invoicing Service was not properly activated. Operation not permitted",
  "status_error_code": 703,
  "session": "FhT3aXe7"
}
```

### 500 — Credentials or the invoicing service failed. 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": "payme_client_key",
  "status_error_code": 1,
  "session": "FhT3aXe7"
}
```