# Create Document

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

## Credentials

No credentials are documented for this endpoint.

## Overview

You can use our Invoices API to generate different documents to serve your business needs.

#### Document types
The documents you can generate can be found in the following guide - [Document Types](/guides-and-use-cases-migrated/lists-statuses/document-types).

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `doc_type` | number | yes | The documents you can generate can be found in the following guide - [Document Types](/guides-and-use-cases-migrated/lists-statuses/document-types). |
| `buyer_name` | string | yes | Buyer's full name |
| `due_date` | string | no | Payment due date |
| `pay_date` | string | no | The date the payment was completed (relevant for doc_type |
| `doc_date` | string | no | Document creation date |
| `currency` | string | yes | The currency of the document |
| `doc_title` | string | no | The title of the document (header) |
| `doc_comments` | string | no | Document description |
| `exchange_rate` | number | no | Currency exchange rate |
| `vat_rate` | number | no | The VAT (Value Added Tax) rate applied |
| `total_excluding_vat` | number | no | Total amount before VAT applied |
| `discount` | number | no | The discount rate (percentage) applied to the document |
| `total_sum_after_discount` | number | no | Total amount with discount rate included |
| `total_sum_after_discount - copy` | number | no | Total amount with discount rate included |
| `total_sum_including_vat` | number | no | Total amount including VAT |
| `total_paid` | number | no | Total amount paid in this document |
| `total_vat` | number | no | Total VAT paid |
| `language` | string | no | Document language |
| `items` | array | no |  |
| `items[].description` | string | yes | Description for item #1 |
| `items[].unit_price` | number | yes | The price per unit (1 item) `unit_price` or `unit_price_with_vat` is required. |
| `items[].vat_exempt` | boolean | no | VAT exempt for the document |
| `items[].quantity` | number | no | Item #1 quantity |
| `items[].unit_price_with_vat` | number | no | Unit (item) price including VAT |
| `items[].currency` | string | no | Currency for item #1 Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `items[].exchange_rate` | number | no | Exchange rate for the document |
| `total_paid_including_vat` | number | no | Total amount paid including VAT |
| `cheques` | array | no | The amount paid using a Cheque |
| `cheques[].sum` | number | yes | The amount paid using Cheque |
| `cheques[].date` | string | no | Cheque deposit date |
| `cheques[].bank` | number | no | The bank number - You can check the [list of banks](/guides-and-use-cases-migrated/lists-statuses/banks-in-israel) for your convenience. |
| `cheques[].branch` | number | no | The bank branch number |
| `cheques[].account` | string | no | The bank account number |
| `cheques[].number` | string | no | The Cheque number |
| `cash` | object | yes | The cash method object |
| `cash.sum` | number | yes | The total amount paid using Cash |
| `bank_transfer` | object | yes | The bank transfer object |
| `bank_transfer.sum` | number | yes | Total amount paid using a bank transfer |
| `bank_transfer.date` | string | no | The date the bank transfer was received |
| `bank_transfer.account` | string | no | The bank account number |
| `paypal` | object | no | The PayPal method object |
| `paypal.sum` | number | yes | Total amount paid using Paypal |
| `paypal.date` | string | yes | The date of when the payment was completed |
| `paypal.transaction_id` | string | no | The external transaction ID (received from Paypal) |
| `paypal.buyer_name` | string | no | The buyer's name |
| `credit_card` | object | no | The credit card object |
| `credit_card.sum` | number | yes | Total amount paid using a credit card |
| `credit_card.installments` | number | no | The number of installments for the payment (1 min, 36 max) |
| `credit_card.first_payment` | number | no | The amount paid in the 1st installment |
| `credit_card.buyer_key` | string | no | If the invoice is paid using a token, buyer key is required |
| `credit_card.number` | string | no | If paid without a token, card number is required |
| `credit_card.type` | string | no | Card brand |
| `credit_card.cvv` | string | no | Card's CVV (3-number code at the back of the card) |
| `credit_card.expiry` | string | no | Expiry date of the card (MMYY) |
| `credit_card.buyer_social_id` | string | no | Buyer's social ID number |
| `credit_card.buyer_name` | string | no | Buyer's full name |
| `credit_card.auth_number` | string | no | Authorization number of the payment |

### Request example

```json
{
  "doc_type": 400,
  "buyer_name": "John Doe",
  "due_date": "2021-08-16T00:00:00.000Z",
  "pay_date": "2021-04-16T00:00:00.000Z",
  "doc_date": "2021-05-25 00:00:00",
  "currency": "ILS",
  "doc_title": "Invoice for John Doe",
  "doc_comments": "Some description about the invoice",
  "exchange_rate": 1,
  "vat_rate": 0.17,
  "total_excluding_vat": 123,
  "discount": 0,
  "total_sum_after_discount": 123,
  "total_sum_including_vat": 140,
  "total_paid": 140,
  "total_vat": 17,
  "total_paid_including_vat": 140,
  "language": "he",
  "items": [
    {
      "description": "Test Item 1",
      "unit_price": 100,
      "vat_exempt": false,
      "quantity": 1,
      "unit_price_with_vat": 117,
      "currency": "ILS",
      "exchange_rate": 1
    },
    {
      "description": "Test Item 2",
      "unit_price": 23,
      "vat_exempt": true,
      "quantity": 1,
      "currency": "ILS"
    }
  ],
  "cheques": [
    {
      "sum": 10,
      "date": "2021-05-16T00:00:00.000Z",
      "bank": 6,
      "branch": 22,
      "account": "123456",
      "number": "0014555"
    },
    {
      "sum": 13,
      "date": "2021-06-16T00:00:00.000Z",
      "bank": 6,
      "branch": 22,
      "account": "123456",
      "number": "0014555"
    }
  ],
  "cash": {
    "sum": 25
  },
  "bank_transfer": {
    "sum": 25,
    "date": "2021-05-16T00:00:00.000Z",
    "account": "123456"
  },
  "paypal": {
    "sum": 25,
    "date": "2021-05-16T00:00:00.000Z",
    "transaction_id": "123456",
    "buyer_name": "John Doe"
  },
  "credit_card": {
    "sum": 25,
    "installments": 1,
    "first_payment": 50,
    "buyer_key": "123456789",
    "number": "4580458045804580",
    "type": "Visa",
    "cvv": "123",
    "expiry": "0323",
    "buyer_social_id": "05001234",
    "buyer_name": "John Doe",
    "auth_number": "123123123"
  }
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/documents' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "doc_type": 400,
  "buyer_name": "John Doe",
  "due_date": "2021-08-16T00:00:00.000Z",
  "pay_date": "2021-04-16T00:00:00.000Z",
  "doc_date": "2021-05-25 00:00:00",
  "currency": "ILS",
  "doc_title": "Invoice for John Doe",
  "doc_comments": "Some description about the invoice",
  "exchange_rate": 1,
  "vat_rate": 0.17,
  "total_excluding_vat": 123,
  "discount": 0,
  "total_sum_after_discount": 123,
  "total_sum_including_vat": 140,
  "total_paid": 140,
  "total_vat": 17,
  "total_paid_including_vat": 140,
  "language": "he",
  "items": [
    {
      "description": "Test Item 1",
      "unit_price": 100,
      "vat_exempt": false,
      "quantity": 1,
      "unit_price_with_vat": 117,
      "currency": "ILS",
      "exchange_rate": 1
    },
    {
      "description": "Test Item 2",
      "unit_price": 23,
      "vat_exempt": true,
      "quantity": 1,
      "currency": "ILS"
    }
  ],
  "cheques": [
    {
      "sum": 10,
      "date": "2021-05-16T00:00:00.000Z",
      "bank": 6,
      "branch": 22,
      "account": "123456",
      "number": "0014555"
    },
    {
      "sum": 13,
      "date": "2021-06-16T00:00:00.000Z",
      "bank": 6,
      "branch": 22,
      "account": "123456",
      "number": "0014555"
    }
  ],
  "cash": {
    "sum": 25
  },
  "bank_transfer": {
    "sum": 25,
    "date": "2021-05-16T00:00:00.000Z",
    "account": "123456"
  },
  "paypal": {
    "sum": 25,
    "date": "2021-05-16T00:00:00.000Z",
    "transaction_id": "123456",
    "buyer_name": "John Doe"
  },
  "credit_card": {
    "sum": 25,
    "installments": 1,
    "first_payment": 50,
    "buyer_key": "123456789",
    "number": "4580458045804580",
    "type": "Visa",
    "cvv": "123",
    "expiry": "0323",
    "buyer_social_id": "05001234",
    "buyer_name": "John Doe",
    "auth_number": "123123123"
  }
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/documents", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "doc_type": 400,
    "buyer_name": "John Doe",
    "due_date": "2021-08-16T00:00:00.000Z",
    "pay_date": "2021-04-16T00:00:00.000Z",
    "doc_date": "2021-05-25 00:00:00",
    "currency": "ILS",
    "doc_title": "Invoice for John Doe",
    "doc_comments": "Some description about the invoice",
    "exchange_rate": 1,
    "vat_rate": 0.17,
    "total_excluding_vat": 123,
    "discount": 0,
    "total_sum_after_discount": 123,
    "total_sum_including_vat": 140,
    "total_paid": 140,
    "total_vat": 17,
    "total_paid_including_vat": 140,
    "language": "he",
    "items": [
      {
        "description": "Test Item 1",
        "unit_price": 100,
        "vat_exempt": false,
        "quantity": 1,
        "unit_price_with_vat": 117,
        "currency": "ILS",
        "exchange_rate": 1
      },
      {
        "description": "Test Item 2",
        "unit_price": 23,
        "vat_exempt": true,
        "quantity": 1,
        "currency": "ILS"
      }
    ],
    "cheques": [
      {
        "sum": 10,
        "date": "2021-05-16T00:00:00.000Z",
        "bank": 6,
        "branch": 22,
        "account": "123456",
        "number": "0014555"
      },
      {
        "sum": 13,
        "date": "2021-06-16T00:00:00.000Z",
        "bank": 6,
        "branch": 22,
        "account": "123456",
        "number": "0014555"
      }
    ],
    "cash": {
      "sum": 25
    },
    "bank_transfer": {
      "sum": 25,
      "date": "2021-05-16T00:00:00.000Z",
      "account": "123456"
    },
    "paypal": {
      "sum": 25,
      "date": "2021-05-16T00:00:00.000Z",
      "transaction_id": "123456",
      "buyer_name": "John Doe"
    },
    "credit_card": {
      "sum": 25,
      "installments": 1,
      "first_payment": 50,
      "buyer_key": "123456789",
      "number": "4580458045804580",
      "type": "Visa",
      "cvv": "123",
      "expiry": "0323",
      "buyer_social_id": "05001234",
      "buyer_name": "John Doe",
      "auth_number": "123123123"
    }
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/documents",
    json={
        "doc_type": 400,
        "buyer_name": "John Doe",
        "due_date": "2021-08-16T00:00:00.000Z",
        "pay_date": "2021-04-16T00:00:00.000Z",
        "doc_date": "2021-05-25 00:00:00",
        "currency": "ILS",
        "doc_title": "Invoice for John Doe",
        "doc_comments": "Some description about the invoice",
        "exchange_rate": 1,
        "vat_rate": 0.17,
        "total_excluding_vat": 123,
        "discount": 0,
        "total_sum_after_discount": 123,
        "total_sum_including_vat": 140,
        "total_paid": 140,
        "total_vat": 17,
        "total_paid_including_vat": 140,
        "language": "he",
        "items": [
            {
                "description": "Test Item 1",
                "unit_price": 100,
                "vat_exempt": False,
                "quantity": 1,
                "unit_price_with_vat": 117,
                "currency": "ILS",
                "exchange_rate": 1,
            },
            {
                "description": "Test Item 2",
                "unit_price": 23,
                "vat_exempt": True,
                "quantity": 1,
                "currency": "ILS",
            },
        ],
        "cheques": [
            {
                "sum": 10,
                "date": "2021-05-16T00:00:00.000Z",
                "bank": 6,
                "branch": 22,
                "account": "123456",
                "number": "0014555",
            },
            {
                "sum": 13,
                "date": "2021-06-16T00:00:00.000Z",
                "bank": 6,
                "branch": 22,
                "account": "123456",
                "number": "0014555",
            },
        ],
        "cash": {
            "sum": 25,
        },
        "bank_transfer": {
            "sum": 25,
            "date": "2021-05-16T00:00:00.000Z",
            "account": "123456",
        },
        "paypal": {
            "sum": 25,
            "date": "2021-05-16T00:00:00.000Z",
            "transaction_id": "123456",
            "buyer_name": "John Doe",
        },
        "credit_card": {
            "sum": 25,
            "installments": 1,
            "first_payment": 50,
            "buyer_key": "123456789",
            "number": "4580458045804580",
            "type": "Visa",
            "cvv": "123",
            "expiry": "0323",
            "buyer_social_id": "05001234",
            "buyer_name": "John Doe",
            "auth_number": "123123123",
        },
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "doc_type": 400,
  "buyer_name": "John Doe",
  "due_date": "2021-08-16T00:00:00.000Z",
  "pay_date": "2021-04-16T00:00:00.000Z",
  "doc_date": "2021-05-25 00:00:00",
  "currency": "ILS",
  "doc_title": "Invoice for John Doe",
  "doc_comments": "Some description about the invoice",
  "exchange_rate": 1,
  "vat_rate": 0.17,
  "total_excluding_vat": 123,
  "discount": 0,
  "total_sum_after_discount": 123,
  "total_sum_including_vat": 140,
  "total_paid": 140,
  "total_vat": 17,
  "total_paid_including_vat": 140,
  "language": "he",
  "items": [
    {
      "description": "Test Item 1",
      "unit_price": 100,
      "vat_exempt": false,
      "quantity": 1,
      "unit_price_with_vat": 117,
      "currency": "ILS",
      "exchange_rate": 1
    },
    {
      "description": "Test Item 2",
      "unit_price": 23,
      "vat_exempt": true,
      "quantity": 1,
      "currency": "ILS"
    }
  ],
  "cheques": [
    {
      "sum": 10,
      "date": "2021-05-16T00:00:00.000Z",
      "bank": 6,
      "branch": 22,
      "account": "123456",
      "number": "0014555"
    },
    {
      "sum": 13,
      "date": "2021-06-16T00:00:00.000Z",
      "bank": 6,
      "branch": 22,
      "account": "123456",
      "number": "0014555"
    }
  ],
  "cash": {
    "sum": 25
  },
  "bank_transfer": {
    "sum": 25,
    "date": "2021-05-16T00:00:00.000Z",
    "account": "123456"
  },
  "paypal": {
    "sum": 25,
    "date": "2021-05-16T00:00:00.000Z",
    "transaction_id": "123456",
    "buyer_name": "John Doe"
  },
  "credit_card": {
    "sum": 25,
    "installments": 1,
    "first_payment": 50,
    "buyer_key": "123456789",
    "number": "4580458045804580",
    "type": "Visa",
    "cvv": "123",
    "expiry": "0323",
    "buyer_social_id": "05001234",
    "buyer_name": "John Doe",
    "auth_number": "123123123"
  }
}
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',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

echo $response;
```

## Responses

### 200 — OK (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status of the request (0 - success, 1 - error) |
| `doc_type` | string | The documents you can generate can be found in the following guide - [Document Types](/guides-and-use-cases-migrated/lists-statuses/document-types). |
| `language` | string | Changes the language of the payment IFRAME to English, as well as the error messages. Default value is Hebrew (he) |
| `due_date` | string | The date on which a seller expects to receive payment from a buyer |
| `pay_date` | string | Payment date |
| `doc_date` | string | The date of document creation |
| `currency` | string | Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `vat_rate` | number | The VAT (Value Added Tax) rate applied. |
| `discount` | number | The discount rate (percentage) applied to the document |
| `total_vat` | number | Total VAT paid |
| `doc_title` | string | The title of the document (header) |
| `buyer_name` | string | The buyer's name |
| `total_paid` | number | Total amount paid in this document |
| `doc_comments` | string | Document description |
| `exchange_rate` | number | Currency exchange rate |
| `total_excluding_vat` | number | Total amount before VAT applied |
| `total_sum_including_vat` | number | Total amount including VAT |
| `total_sum_after_discount` | number | Total amount with discount rate included |
| `total_paid_including_vat` | number | Total amount paid including VAT |
| `cash` | object | The cash method object |
| `cash.sum` | number | The total amount paid using Cash |
| `cheques` | array | The amount paid using a Cheque |
| `cheques[].sum` | number | The amount paid using Cheque |
| `cheques[].date` | string | Cheque deposit date |
| `cheques[].bank` | number | The bank number - You can check the [list of banks](/guides-and-use-cases-migrated/lists-statuses/banks-in-israel) for your convenience. |
| `cheques[].branch` | number | The bank branch number |
| `cheques[].account` | string | The bank account number |
| `cheques[].number` | string | The Cheque number |
| `bank_transfer` | object | The bank transfer object |
| `bank_transfer.sum` | number | Total amount paid using a bank transfer |
| `bank_transfer.date` | string | The date the bank transfer was received |
| `bank_transfer.account` | string | The bank account number |
| `credit_card` | object | The credit card object |
| `credit_card.sum` | number | Total amount paid using a credit card |
| `credit_card.installments` | number | The number of installments for the payment (1 min, 36 max) |
| `credit_card.first_payment` | number | The amount paid in the 1st installment |
| `credit_card.number` | string | If paid without a token, card number is required |
| `credit_card.type` | string | Card brand |
| `credit_card.cvv` | string | Card's CVV (3-number code at the back of the card) |
| `credit_card.buyer_social_id` | string | Buyer's social ID number |
| `credit_card.buyer_name` | string | Buyer's full name |
| `credit_card.auth_number` | string | Authorization number of the payment |
| `credit_card.expiry` | string | Expiry date of the card (MMYY) |
| `paypal` | object | The PayPal method object |
| `paypal.sum` | number | Total amount paid using Paypal |
| `paypal.date` | string | The date of when the payment was completed |
| `paypal.transaction_id` | string | The external transaction ID (received from Paypal) |
| `paypal.buyer_name` | string | The buyer's name |
| `items` | array |  |
| `items[].quantity` | number | Item #1 quantity |
| `items[].description` | string | Description for item #1 |
| `items[].unit_price` | number | The price per unit (1 item) |
| `items[].vat_exempt` | boolean | VAT exempt for the document |
| `items[].currency` | string | Currency for item #1 Sale currency. [3-letter ISO 4217 name](https://en.wikipedia.org/wiki/ISO_4217). |
| `items[].unit_price_with_vat` | number | Unit (item) price including VAT |
| `items[].exchange_rate` | number | Exchange rate for the document |
| `doc_id` | string | Document ID number |
| `doc_url` | string | Document URL |

```json
{
  "status_code": 0,
  "doc_type": "400",
  "language": "he",
  "due_date": "2021-08-16T00:00:00.000Z",
  "pay_date": "2021-04-16T00:00:00.000Z",
  "doc_date": "2021-05-25 00:00:00",
  "currency": "ILS",
  "vat_rate": 0.17,
  "discount": 0,
  "total_vat": 17,
  "doc_title": "Invoice for John Doe",
  "buyer_name": "John Doe",
  "total_paid": 140,
  "doc_comments": "Some description about the invoice",
  "exchange_rate": 1,
  "total_excluding_vat": 123,
  "total_sum_including_vat": 140,
  "total_sum_after_discount": 123,
  "total_paid_including_vat": 140,
  "cash": {
    "sum": 25
  },
  "cheques": [
    {
      "sum": 10,
      "date": "2021-05-16T00:00:00.000Z",
      "bank": 6,
      "branch": 22,
      "account": "123456",
      "number": "0014555"
    },
    {
      "sum": 13,
      "date": "2021-06-16T00:00:00.000Z",
      "bank": 6,
      "branch": 22,
      "account": "123456",
      "number": "0014555"
    }
  ],
  "bank_transfer": {
    "sum": 25,
    "date": "2021-05-16T00:00:00.000Z",
    "account": "123456"
  },
  "credit_card": {
    "sum": 0,
    "installments": 1,
    "first_payment": 50,
    "number": "4580458045804580",
    "type": "Visa",
    "cvv": "123",
    "buyer_social_id": "05001234",
    "buyer_name": "John Doe",
    "auth_number": "123123123",
    "expiry": "323"
  },
  "paypal": {
    "sum": 50,
    "date": "2021-05-16T00:00:00.000Z",
    "transaction_id": "123456",
    "buyer_name": "John Doe"
  },
  "items": [
    {
      "quantity": 1,
      "description": "Test Item 1",
      "unit_price": 100,
      "vat_exempt": false,
      "currency": "ILS",
      "unit_price_with_vat": 117,
      "exchange_rate": 1
    },
    {
      "quantity": 1,
      "description": "Test Item 2",
      "unit_price": 23,
      "vat_exempt": true,
      "currency": "ILS"
    }
  ],
  "doc_id": "fa397fce-aee6-4c6d-ae9c-273ae1e3a317",
  "doc_url": "https://invoice-staging.paymeservice.com/documents/fa397fce-aee6-4c6d-ae9c-273ae1e3a317"
}
```

### 400 — Bad Request (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number |  |
| `status_error_details` | string |  |
| `status_additional_info` | object |  |
| `status_additional_info.doc_type` | array |  |
| `status_additional_info.items` | array |  |
| `status_additional_info.buyer_name` | array |  |
| `status_error_code` | number |  |

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