# Create income document

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

- Sandbox: your partner domain on the Keep sandbox: `POST https://<partner_domain>.keep.co.il/seller/api/documents/income`
- Production: your partner domain: `POST https://<partner_domain>.keep.co.il/seller/api/documents/income`

## Credentials

- Header `Authorization: Bearer <token>`

Create a new income document (invoice, receipt, deal, etc.) using the new invoicing service.

## More examples

Amounts are in agorot (1 ILS = 100 agorot).

### Receipt (cash)

```json
{
  "type": "receipt",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "docLang": "he",
  "items": [
    {
      "name": "Product Sale",
      "quantity": 2,
      "itemNetPrice": 50000,
      "itemTotalPrice": 58500,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "totalAmount": 117000,
  "totalPaid": 117000,
  "originTaxDeduction": 0,
  "cash": {
    "date": "2024-01-15",
    "amount": 117000
  }
}
```

### Invoice + Receipt (bank transfer)

```json
{
  "type": "invrec",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "docLang": "he",
  "items": [
    {
      "name": "Annual Subscription",
      "quantity": 1,
      "itemNetPrice": 240000,
      "itemTotalPrice": 280800,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 240000,
  "totalWithoutVatAmount": 240000,
  "vatAmount": 40800,
  "totalAmount": 280800,
  "totalPaid": 280800,
  "originTaxDeduction": 0,
  "bank-transfer": {
    "date": "2024-01-15",
    "amount": 280800,
    "bankNumber": "12",
    "branchNumber": 456,
    "accountNumber": 123456
  }
}
```

### Receipt with multiple payments

```json
{
  "type": "receipt",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "docLang": "he",
  "items": [
    {
      "name": "Professional Services",
      "quantity": 10,
      "itemNetPrice": 20000,
      "itemTotalPrice": 23400,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "totalAmount": 234000,
  "totalPaid": 234000,
  "originTaxDeduction": 0,
  "cash": {
    "date": "2024-01-15",
    "amount": 34000
  },
  "cc": {
    "date": "2024-01-15",
    "amount": 200000,
    "last4Digits": "5678"
  }
}
```

### Invoice with payment link

```json
{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-01-30",
  "docLang": "en",
  "items": [
    {
      "name": "Online Course Subscription",
      "quantity": 1,
      "itemNetPrice": 79900,
      "itemTotalPrice": 93483,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 79900,
  "totalWithoutVatAmount": 79900,
  "vatAmount": 13583,
  "totalAmount": 93483,
  "payment": {
    "isEnabled": true,
    "clientEmail": "buyer@example.com"
  }
}
```

### Receipt with cheque

```json
{
  "type": "receipt",
  "client": {
    "name": "Example Buyer",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "docLang": "he",
  "items": [
    {
      "name": "Equipment Purchase",
      "quantity": 1,
      "itemNetPrice": 1500000,
      "itemTotalPrice": 1755000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "totalAmount": 1755000,
  "totalPaid": 1755000,
  "originTaxDeduction": 0,
  "cheque": {
    "date": "2024-02-15",
    "receivedDate": "2024-01-15",
    "amount": 1755000,
    "chequeNumber": 1234567,
    "bankNumber": "10",
    "branchNumber": 123,
    "accountNumber": 987654
  }
}
```

### VAT-exempt items

```json
{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Services (VAT exempt)",
      "quantity": 1,
      "itemNetPrice": 500000,
      "itemTotalPrice": 500000,
      "itemCurrency": "ILS",
      "isNoItemVat": true
    },
    {
      "name": "Training Materials",
      "quantity": 1,
      "itemNetPrice": 100000,
      "itemTotalPrice": 117000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 600000,
  "totalWithoutVatAmount": 600000,
  "vatAmount": 17000,
  "totalAmount": 617000
}
```

## After the 202

The document is issued asynchronously. The `202` response gives its `id` and `url` at once; the result reaches each URL in `callbacks`. A callback delivery that fails is retried after 60 seconds, three attempts in all.

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | yes | Document type Allowed values: `invoice`, `receipt`, `invrec`, `deal`, `refund`, `offer`. |
| `client` | object | yes |  |
| `client.name` | string | yes | Client/customer name, at most 255 characters. |
| `client.email` | string | no | Client email address |
| `client.phone` | string | no | Client phone number |
| `client.socialId` | string | no | Client's social/business ID number (ת.ז. / ח.פ.). Exactly 9 digits. Required when the document total is 23,600 ILS or more. |
| `currency` | string | yes | Document currency (currently only ILS supported) |
| `docValueDate` | string | yes | Document value date |
| `dueDate` | string | no | Payment due date (optional). |
| `title` | string | no | Document title (optional), at most 255 characters. |
| `docLang` | string | yes | Document language Allowed values: `he`, `en`. |
| `items` | array | yes | Document line items |
| `items[].name` | string | yes | Item name/description, at most 255 characters. |
| `items[].quantity` | number | yes | Item quantity, at least 1. |
| `items[].itemNetPrice` | number | yes | Item net price (before VAT) |
| `items[].itemTotalPrice` | number | no | Item total price (calculated). Required for `invoice`, `invrec`, `deal`, `refund` and `offer`. |
| `items[].itemSumNetTotalPrice` | number | no | Item sum net total price (quantity * itemNetPrice) |
| `items[].itemCurrency` | string | yes | Item currency |
| `items[].isNoItemVat` | boolean | no | VAT exempt flag (true = no VAT for this item). Required for `invoice`, `invrec`, `deal`, `refund` and `offer`. |
| `bankDetails` | object | no | Bank account details for payment |
| `bankDetails.bankName` | string | no | Bank name |
| `bankDetails.branchNumber` | number | no | Branch number |
| `bankDetails.accountNumber` | number | no | Account number |
| `bankDetails.accountName` | string | no | Account holder name |
| `bankDetails.IBAN` | string | no | IBAN number |
| `subTotal` | number | no | Subtotal before discount. Required for `invoice`, `invrec`, `deal`, `refund` and `offer`. |
| `discount` | number | no | Discount amount |
| `totalWithoutVatAmount` | number | no | Total amount without VAT. Required for `invoice`, `invrec`, `deal`, `refund` and `offer`. |
| `vatAmount` | number | no | VAT amount. Required for `invoice`, `invrec`, `deal`, `refund` and `offer`. |
| `totalAmount` | number | yes | Total amount including VAT |
| `totalPaid` | number | no | Total amount paid. Required for `receipt` and `invrec`, and must equal `totalAmount`. |
| `originTaxDeduction` | number | no | Tax deduction at source (ניכוי מס במקור). Required for `receipt` and `invrec`; send `0` when there is none. |
| `comment` | string | no | Document comments/notes, at most 255 characters. |
| `cash` | object | no | Cash payment details |
| `cash.date` | string | yes | Payment date |
| `cash.amount` | number | yes | Payment amount |
| `cc` | object | no | Credit card payment details |
| `cc.date` | string | yes | Payment date |
| `cc.amount` | number | yes | Payment amount |
| `cc.last4Digits` | string | no | Last 4 digits of card |
| `bank-transfer` | object | no | Bank transfer payment details |
| `bank-transfer.date` | string | yes | Payment date |
| `bank-transfer.amount` | number | yes | Payment amount |
| `bank-transfer.bankNumber` | string | no | Bank code |
| `bank-transfer.branchNumber` | integer | no | Branch number |
| `bank-transfer.accountNumber` | integer | yes | Account number |
| `cheque` | object | no | Cheque payment details |
| `cheque.date` | string | yes | Cheque date |
| `cheque.receivedDate` | string | yes | Date cheque was received |
| `cheque.amount` | number | yes | Payment amount |
| `cheque.chequeNumber` | number | yes | Cheque number |
| `cheque.bankNumber` | string | no | Bank code |
| `cheque.branchNumber` | integer | no | Branch number |
| `cheque.accountNumber` | integer | no | Account number |
| `e-wallet` | object | no | E-wallet payment details (PayPal, Bit, etc.) |
| `e-wallet.date` | string | yes | Payment date |
| `e-wallet.amount` | number | yes | Payment amount |
| `e-wallet.appType` | string | yes | Wallet app name |
| `e-wallet.nameOfPayingAccount` | string | no |  |
| `e-wallet.transactionRefNumber` | string | no |  |
| `e-wallet.additionalDetails` | string | no | At most 255 characters. |
| `payment` | object | no | Payment link settings (for invoice/deal) |
| `payment.isEnabled` | boolean | yes | Enable payment link |
| `payment.clientEmail` | string | no | Email to send payment link to. One of the two is required when `isEnabled` is true. |
| `payment.clientPhone` | string | no | Phone to send payment link to. One of the two is required when `isEnabled` is true. |
| `callbacks` | object | no | Callback URLs for the asynchronous result. Each must be an `http` or `https` URL on a public host. |
| `callbacks.success` | array | no | URLs called when the document is issued. Body: `{ "payload": <the document, as Get income document returns it> }`. |
| `callbacks.error` | array | no | URLs called when issuing fails. Body: `{ "document": { "id": "<id from the 202>" }, "error": <reason> }`. A failed document is removed: a later Get income document with that id returns `payload: null`. |

### Request example

```json
{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com",
    "phone": "0500000002",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Service",
      "quantity": 1,
      "itemNetPrice": 100000,
      "itemTotalPrice": 117000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 100000,
  "totalWithoutVatAmount": 100000,
  "vatAmount": 17000,
  "totalAmount": 117000,
  "comment": "Thank you for your business"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://<partner_domain>.keep.co.il/seller/api/documents/income' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com",
    "phone": "0500000002",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Service",
      "quantity": 1,
      "itemNetPrice": 100000,
      "itemTotalPrice": 117000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 100000,
  "totalWithoutVatAmount": 100000,
  "vatAmount": 17000,
  "totalAmount": 117000,
  "comment": "Thank you for your business"
}'
```

### Node.js

```javascript
const response = await fetch("https://<partner_domain>.keep.co.il/seller/api/documents/income", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "type": "invoice",
    "client": {
      "name": "Example Buyer",
      "email": "buyer@example.com",
      "phone": "0500000002",
      "socialId": "123456782"
    },
    "currency": "ILS",
    "docValueDate": "2024-01-15",
    "dueDate": "2024-02-15",
    "docLang": "he",
    "items": [
      {
        "name": "Consulting Service",
        "quantity": 1,
        "itemNetPrice": 100000,
        "itemTotalPrice": 117000,
        "itemCurrency": "ILS",
        "isNoItemVat": false
      }
    ],
    "subTotal": 100000,
    "totalWithoutVatAmount": 100000,
    "vatAmount": 17000,
    "totalAmount": 117000,
    "comment": "Thank you for your business"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://<partner_domain>.keep.co.il/seller/api/documents/income",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "type": "invoice",
        "client": {
            "name": "Example Buyer",
            "email": "buyer@example.com",
            "phone": "0500000002",
            "socialId": "123456782",
        },
        "currency": "ILS",
        "docValueDate": "2024-01-15",
        "dueDate": "2024-02-15",
        "docLang": "he",
        "items": [
            {
                "name": "Consulting Service",
                "quantity": 1,
                "itemNetPrice": 100000,
                "itemTotalPrice": 117000,
                "itemCurrency": "ILS",
                "isNoItemVat": False,
            },
        ],
        "subTotal": 100000,
        "totalWithoutVatAmount": 100000,
        "vatAmount": 17000,
        "totalAmount": 117000,
        "comment": "Thank you for your business",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "type": "invoice",
  "client": {
    "name": "Example Buyer",
    "email": "buyer@example.com",
    "phone": "0500000002",
    "socialId": "123456782"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Service",
      "quantity": 1,
      "itemNetPrice": 100000,
      "itemTotalPrice": 117000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 100000,
  "totalWithoutVatAmount": 100000,
  "vatAmount": 17000,
  "totalAmount": 117000,
  "comment": "Thank you for your business"
}
BODY;

$ch = curl_init('https://<partner_domain>.keep.co.il/seller/api/documents/income');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

echo $response;
```

## Responses

### 202 — Document accepted (success)

| Field | Type | Description |
| --- | --- | --- |
| `payload` | object |  |
| `payload.id` | string | Created document ID |
| `payload.url` | string | URL to download/view the document |

### 400 — Bad Request (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | HTTP status code |
| `message` | string | Error message(s) |
| `error` | string | Error type |

```json
{
  "statusCode": 400,
  "message": [
    "Validation failed"
  ],
  "error": "Bad Request"
}
```

### 401 — Unauthorized (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | HTTP status code |
| `message` | string | Error message(s) |
| `error` | string | Error type |

```json
{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}
```

### 403 — Forbidden. The seller cannot issue documents now: invoicing is not set up, the trial has ended, or the seller is closed. (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | HTTP status code |
| `message` | string | Error message(s) |
| `error` | string | Error type |

### 422 — Unprocessable Entity. Messages include: the client `socialId` is required for documents of 23,600 ILS and above; `Your invoice Israel token is invalid` (with `renewTokenUrl`, where the seller renews the Israel Tax Authority connection); `Record already exists`. (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | HTTP status code |
| `message` | string | Error message(s) |
| `error` | string | Error type |

### 429 — Too many requests. The body is plain text. (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | HTTP status code |
| `message` | string | Error message(s) |
| `error` | string | Error type |