# Keep

## Partner Authorization

- [Prerequisites](https://docs-staging.payme.io/keep/partner-authorization/prerequisites): Partner authorization layer protects the Partner's data on the Keep domain against unauthorized access and mutation.

# Prerequisites

Partner authorization layer protects the Partner's data on the Keep domain against unauthorized access and mutation.

The Keep API uses API keys to authenticate requests. Before starting integration you must receive your Partner API keys from your Account Manager:

- `Client ID`
- `Client Secret`


Your API keys carry many privileges, so be sure to keep them **secure**! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. The API keys must be provided during any interactions via [OAuth2 Access and Refresh Tokens](https://docs-staging.payme.io/docs/keep/b3A6Mjg1MjU2MTQ) endpoint.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

- [Authorization Flow](https://docs-staging.payme.io/keep/partner-authorization/authorization-flow): This document provides a high-level overview of the Keep API authentication system.

# Authorization Overview

This document provides a high-level overview of the Keep API authentication system.

---

## Introduction

The PayMe API uses OAuth 2.0 for secure authentication. API integrators authenticate using the **Client Credentials** flow, which is designed for server-to-server communication where no user interaction is required.

---

## How It Works

> **Authentication Flow**
> 1. Your server requests an access token using your client credentials
> 2. The API returns an access token and refresh token
> 3. Use the access token to make authorized API requests
> 4. When the access token expires, use the refresh token to obtain a new one
> 5. When the refresh token expires, repeat from step 1

---

## Authentication Methods

### Client Credentials

This is the primary authentication method for API integrators. Your server authenticates directly with the PayMe API using a client ID and client secret provided during onboarding.

> **When to use:** Server-to-server integrations, backend services, automated processes

### Refresh Token

Used to obtain a new access token without re-authenticating with credentials. This ensures continuous API access without storing sensitive credentials for repeated use.

> **When to use:** When your current access token has expired or is about to expire

---

## Tokens

### Access Token

- Used to authenticate API requests
- Short-lived (typically 1 hour)
- Must be included in the `Authorization` header of every API request
- Format: `Bearer <token>`

### Refresh Token

- Used to obtain new access tokens
- Long-lived (typically 30 days)
- Should be stored securely
- Cannot be used to make API requests directly

---

## Scopes

Scopes define what resources and actions your integration can access.

| Scope | Description |
|-------|-------------|
| `partner-api` | Access to partner-level endpoints and resources |
| `seller-api` | Access to seller-level endpoints and resources |

Request only the scopes your integration needs to follow the principle of least privilege.

---

## Security Considerations

> **Important Security Practices**
> - Never expose your client secret in client-side code
> - Always use HTTPS for all API communications
> - Store tokens securely using encryption
> - Implement token refresh before expiration
> - Rotate credentials periodically

---

## Getting Started

1. **Obtain Credentials** - Contact Keep to receive your `client_id` and `client_secret`
2. **Request Access Token** - Use the Client Credentials flow to obtain tokens
3. **Make API Requests** - Include the access token in your API calls
4. **Handle Token Refresh** - Implement logic to refresh tokens before they expire

---

## Next Steps

For detailed implementation instructions including request/response formats and code examples, see the [Authorization Flow](authorization-flow.md) documentation.


## Seller API

- [List income documents](https://docs-staging.payme.io/keep/seller-api/listsellerincomedocuments): GET /seller/api/documents/income — List income documents

# List income documents

- Sandbox: `GET https://sandbox.payme.io/api/seller/api/documents/income`
- Production: `GET https://live.payme.io/api/seller/api/documents/income`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve a list of income documents for the authenticated seller.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `page` | query | integer | no | Page number |
| `limit` | query | integer | no | Items per page |
| `docType` | query | string | no | Filter by document type |
| `fromDate` | query | string | no | Filter documents from this date |
| `toDate` | query | string | no | Filter documents until this date |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/seller/api/documents/income' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/seller/api/documents/income", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/seller/api/documents/income",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/seller/api/documents/income');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Successful response (success)

| Field | Type | Description |
| --- | --- | --- |
| `payload` | object |  |
| `payload.page` | integer |  |
| `payload.limit` | integer |  |
| `payload.total` | integer |  |
| `payload.items` | array |  |
| `payload.items[].id` | string |  |
| `payload.items[].docType` | string |  |
| `payload.items[].docNumber` | string | Document number |
| `payload.items[].docRegulationNumber` | string | Tax authority regulation number |
| `payload.items[].valueDate` | string |  |
| `payload.items[].dueDate` | string |  |
| `payload.items[].client` | object |  |
| `payload.items[].client.name` | string | Client/customer name |
| `payload.items[].client.email` | string | Client email address |
| `payload.items[].client.phone` | string | Client phone number |
| `payload.items[].client.socialId` | string | Client's social/business ID number (ת.ז. / ח.פ.) |
| `payload.items[].totalWithoutVat` | number |  |
| `payload.items[].vatAmount` | number |  |
| `payload.items[].totalAmount` | number |  |
| `payload.items[].currency` | string |  |
| `payload.items[].status` | string |  |
| `payload.items[].url` | string | Document download URL |
| `payload.items[].createdAt` | string |  |

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

- [Seller API](https://docs-staging.payme.io/keep/seller-api/overview): The Seller API lets accounting integrations create, retrieve, cancel, and preview seller income documents such as invoices and receipts. This page is the editable landing for the Seller API category.

# Seller API

The Seller API lets you create and manage **seller income documents** — invoices, receipts, and previews — within the Keep accounting service.

Use it to:

- List a seller's income documents
- Create a new income document
- Retrieve a single income document
- Cancel an income document
- Generate a document preview

The available endpoints are listed below. Edit this page to add your own introduction, prerequisites, and examples.

- [Create income document](https://docs-staging.payme.io/keep/seller-api/createsellerincomedocument): POST /seller/api/documents/income — Create income document

# Create income document

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

## Credentials

- Header `Authorization: Bearer <token>`

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

## 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 |
| `client` | object | yes |  |
| `client.name` | string | yes | Client/customer name |
| `client.email` | string | no | Client email address |
| `client.phone` | string | no | Client phone number |
| `client.socialId` | string | no | Client's social/business ID number (ת.ז. / ח.פ.) |
| `currency` | string | yes | Document currency (currently only ILS supported) |
| `docValueDate` | string | yes | Document value date |
| `dueDate` | string | no | Payment due date (required for invoice, deal, offer) |
| `title` | string | no | Document title (optional) |
| `docLang` | string | yes | Document language |
| `items` | array | yes | Document line items |
| `items[].name` | string | yes | Item name/description |
| `items[].quantity` | number | yes | Item quantity |
| `items[].itemNetPrice` | number | yes | Item net price (before VAT) |
| `items[].itemTotalPrice` | number | no | Item total price (calculated) |
| `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) |
| `bankDetails` | object | no | Bank account details for payment |
| `bankDetails.bankName` | string | no | Bank name |
| `bankDetails.branchNumber` | string | no | Branch number |
| `bankDetails.accountNumber` | string | no | Account number |
| `bankDetails.accountName` | string | no | Account holder name |
| `bankDetails.IBAN` | string | no | IBAN number |
| `subTotal` | number | no | Subtotal before discount |
| `discount` | number | no | Discount amount |
| `totalWithoutVatAmount` | number | no | Total amount without VAT |
| `vatAmount` | number | no | VAT amount |
| `totalAmount` | number | yes | Total amount including VAT |
| `totalPaid` | number | no | Total amount paid (required for receipts) |
| `originTaxDeduction` | number | no | Tax deduction at source (ניכוי מס במקור) |
| `comment` | string | no | Document comments/notes |
| `paymentCash` | object | no | Cash payment details |
| `paymentCash.date` | string | yes | Payment date |
| `paymentCash.amount` | number | yes | Payment amount |
| `paymentCreditCard` | object | no | Credit card payment details |
| `paymentCreditCard.date` | string | yes | Payment date |
| `paymentCreditCard.amount` | number | yes | Payment amount |
| `paymentCreditCard.last4Digits` | string | no | Last 4 digits of card |
| `paymentBankTransfer` | object | no | Bank transfer payment details |
| `paymentBankTransfer.date` | string | yes | Payment date |
| `paymentBankTransfer.amount` | number | yes | Payment amount |
| `paymentBankTransfer.bankNumber` | integer | no | Bank code |
| `paymentBankTransfer.branchNumber` | integer | no | Branch number |
| `paymentBankTransfer.accountNumber` | integer | no | Account number |
| `paymentCheque` | object | no | Cheque payment details |
| `paymentCheque.date` | string | yes | Cheque date |
| `paymentCheque.receivedDate` | string | yes | Date cheque was received |
| `paymentCheque.amount` | number | yes | Payment amount |
| `paymentCheque.chequeNumber` | string | yes | Cheque number |
| `paymentCheque.bankNumber` | integer | no | Bank code |
| `paymentCheque.branchNumber` | integer | no | Branch number |
| `paymentCheque.accountNumber` | integer | no | Account number |
| `paymentEWallet` | object | no | E-wallet payment details (PayPal, Bit, etc.) |
| `paymentEWallet.date` | string | yes | Payment date |
| `paymentEWallet.amount` | number | yes | Payment amount |
| `paymentEWallet.walletType` | string | yes | E-wallet type |
| `payment` | object | no | Payment link settings (for invoice/deal) |
| `payment.isEnabled` | boolean | no | Enable payment link |
| `payment.clientEmail` | string | no | Email to send payment link to |
| `payment.clientPhone` | string | no | Phone to send payment link to |
| `callbacks` | object | no | Callback URLs for async notifications |
| `callbacks.success` | array | no | URLs to call on success |
| `callbacks.error` | array | no | URLs to call on error |

### Request example

```json
{
  "type": "invoice",
  "client": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "0500000002",
    "socialId": "123456789"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Service",
      "quantity": 1,
      "itemNetPrice": 1000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 1000,
  "totalWithoutVatAmount": 1000,
  "vatAmount": 170,
  "totalAmount": 1170,
  "comment": "Thank you for your business"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/seller/api/documents/income' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "type": "invoice",
  "client": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "0500000002",
    "socialId": "123456789"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Service",
      "quantity": 1,
      "itemNetPrice": 1000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 1000,
  "totalWithoutVatAmount": 1000,
  "vatAmount": 170,
  "totalAmount": 1170,
  "comment": "Thank you for your business"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/seller/api/documents/income", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "type": "invoice",
    "client": {
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "0500000002",
      "socialId": "123456789"
    },
    "currency": "ILS",
    "docValueDate": "2024-01-15",
    "dueDate": "2024-02-15",
    "docLang": "he",
    "items": [
      {
        "name": "Consulting Service",
        "quantity": 1,
        "itemNetPrice": 1000,
        "itemCurrency": "ILS",
        "isNoItemVat": false
      }
    ],
    "subTotal": 1000,
    "totalWithoutVatAmount": 1000,
    "vatAmount": 170,
    "totalAmount": 1170,
    "comment": "Thank you for your business"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/seller/api/documents/income",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "type": "invoice",
        "client": {
            "name": "John Doe",
            "email": "john@example.com",
            "phone": "0500000002",
            "socialId": "123456789",
        },
        "currency": "ILS",
        "docValueDate": "2024-01-15",
        "dueDate": "2024-02-15",
        "docLang": "he",
        "items": [
            {
                "name": "Consulting Service",
                "quantity": 1,
                "itemNetPrice": 1000,
                "itemCurrency": "ILS",
                "isNoItemVat": False,
            },
        ],
        "subTotal": 1000,
        "totalWithoutVatAmount": 1000,
        "vatAmount": 170,
        "totalAmount": 1170,
        "comment": "Thank you for your business",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "type": "invoice",
  "client": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "0500000002",
    "socialId": "123456789"
  },
  "currency": "ILS",
  "docValueDate": "2024-01-15",
  "dueDate": "2024-02-15",
  "docLang": "he",
  "items": [
    {
      "name": "Consulting Service",
      "quantity": 1,
      "itemNetPrice": 1000,
      "itemCurrency": "ILS",
      "isNoItemVat": false
    }
  ],
  "subTotal": 1000,
  "totalWithoutVatAmount": 1000,
  "vatAmount": 170,
  "totalAmount": 1170,
  "comment": "Thank you for your business"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/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

### 201 — Document created successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Created document ID |
| `url` | string | URL to download/view the document |
| `docRegulationNumber` | string | Tax authority regulation number (מספר אסמכתא) |

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

- [Get income document](https://docs-staging.payme.io/keep/seller-api/getsellerincomedocument): GET /seller/api/documents/income/{id} — Get income document

# Get income document

- Sandbox: `GET https://sandbox.payme.io/api/seller/api/documents/income/{id}`
- Production: `GET https://live.payme.io/api/seller/api/documents/income/{id}`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve a specific income document by ID.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Document ID |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/seller/api/documents/income/<id>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/seller/api/documents/income/<id>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/seller/api/documents/income/<id>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/seller/api/documents/income/<id>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Successful response (success)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `docType` | string |  |
| `docNumber` | string | Document number |
| `docRegulationNumber` | string | Tax authority regulation number |
| `valueDate` | string |  |
| `dueDate` | string |  |
| `client` | object |  |
| `client.name` | string | Client/customer name |
| `client.email` | string | Client email address |
| `client.phone` | string | Client phone number |
| `client.socialId` | string | Client's social/business ID number (ת.ז. / ח.פ.) |
| `totalWithoutVat` | number |  |
| `vatAmount` | number |  |
| `totalAmount` | number |  |
| `currency` | string |  |
| `status` | string |  |
| `url` | string | Document download URL |
| `createdAt` | string |  |

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

### 404 — Not Found (error)

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

```json
{
  "statusCode": 404,
  "message": "Document not found",
  "error": "Not Found"
}
```

- [Cancel income document](https://docs-staging.payme.io/keep/seller-api/cancelsellerincomedocument): POST /seller/api/documents/income/{id}/cancel — Cancel income document

# Cancel income document

- Sandbox: `POST https://sandbox.payme.io/api/seller/api/documents/income/{id}/cancel`
- Production: `POST https://live.payme.io/api/seller/api/documents/income/{id}/cancel`

## Credentials

- Header `Authorization: Bearer <token>`

Cancel an existing income document. This will create a cancellation record.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | Document ID to cancel |

## Request body

Content type: `application/json`

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/seller/api/documents/income/<id>/cancel' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/seller/api/documents/income/<id>/cancel", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({}),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/seller/api/documents/income/<id>/cancel",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={},
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/seller/api/documents/income/<id>/cancel');
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

### 200 — Document cancelled successfully (success)

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

### 404 — Not Found (error)

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

```json
{
  "statusCode": 404,
  "message": "Document not found",
  "error": "Not Found"
}
```

- [Generate document preview](https://docs-staging.payme.io/keep/seller-api/previewsellerincomedocument): POST /seller/api/documents/income/preview — Generate document preview

# Generate document preview

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

## Credentials

- Header `Authorization: Bearer <token>`

Generate a preview of an income document without saving it.

## 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 |
| `client` | object | yes |  |
| `client.name` | string | yes | Client/customer name |
| `client.email` | string | no | Client email address |
| `client.phone` | string | no | Client phone number |
| `client.socialId` | string | no | Client's social/business ID number (ת.ז. / ח.פ.) |
| `currency` | string | yes | Document currency (currently only ILS supported) |
| `docValueDate` | string | yes | Document value date |
| `dueDate` | string | no | Payment due date (required for invoice, deal, offer) |
| `title` | string | no | Document title (optional) |
| `docLang` | string | yes | Document language |
| `items` | array | yes | Document line items |
| `items[].name` | string | yes | Item name/description |
| `items[].quantity` | number | yes | Item quantity |
| `items[].itemNetPrice` | number | yes | Item net price (before VAT) |
| `items[].itemTotalPrice` | number | no | Item total price (calculated) |
| `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) |
| `bankDetails` | object | no | Bank account details for payment |
| `bankDetails.bankName` | string | no | Bank name |
| `bankDetails.branchNumber` | string | no | Branch number |
| `bankDetails.accountNumber` | string | no | Account number |
| `bankDetails.accountName` | string | no | Account holder name |
| `bankDetails.IBAN` | string | no | IBAN number |
| `subTotal` | number | no | Subtotal before discount |
| `discount` | number | no | Discount amount |
| `totalWithoutVatAmount` | number | no | Total amount without VAT |
| `vatAmount` | number | no | VAT amount |
| `totalAmount` | number | yes | Total amount including VAT |
| `totalPaid` | number | no | Total amount paid (required for receipts) |
| `originTaxDeduction` | number | no | Tax deduction at source (ניכוי מס במקור) |
| `comment` | string | no | Document comments/notes |
| `paymentCash` | object | no | Cash payment details |
| `paymentCash.date` | string | yes | Payment date |
| `paymentCash.amount` | number | yes | Payment amount |
| `paymentCreditCard` | object | no | Credit card payment details |
| `paymentCreditCard.date` | string | yes | Payment date |
| `paymentCreditCard.amount` | number | yes | Payment amount |
| `paymentCreditCard.last4Digits` | string | no | Last 4 digits of card |
| `paymentBankTransfer` | object | no | Bank transfer payment details |
| `paymentBankTransfer.date` | string | yes | Payment date |
| `paymentBankTransfer.amount` | number | yes | Payment amount |
| `paymentBankTransfer.bankNumber` | integer | no | Bank code |
| `paymentBankTransfer.branchNumber` | integer | no | Branch number |
| `paymentBankTransfer.accountNumber` | integer | no | Account number |
| `paymentCheque` | object | no | Cheque payment details |
| `paymentCheque.date` | string | yes | Cheque date |
| `paymentCheque.receivedDate` | string | yes | Date cheque was received |
| `paymentCheque.amount` | number | yes | Payment amount |
| `paymentCheque.chequeNumber` | string | yes | Cheque number |
| `paymentCheque.bankNumber` | integer | no | Bank code |
| `paymentCheque.branchNumber` | integer | no | Branch number |
| `paymentCheque.accountNumber` | integer | no | Account number |
| `paymentEWallet` | object | no | E-wallet payment details (PayPal, Bit, etc.) |
| `paymentEWallet.date` | string | yes | Payment date |
| `paymentEWallet.amount` | number | yes | Payment amount |
| `paymentEWallet.walletType` | string | yes | E-wallet type |
| `payment` | object | no | Payment link settings (for invoice/deal) |
| `payment.isEnabled` | boolean | no | Enable payment link |
| `payment.clientEmail` | string | no | Email to send payment link to |
| `payment.clientPhone` | string | no | Phone to send payment link to |
| `callbacks` | object | no | Callback URLs for async notifications |
| `callbacks.success` | array | no | URLs to call on success |
| `callbacks.error` | array | no | URLs to call on error |

### Request example

No example is documented; this template is generated from the fields — replace the placeholder values.

```json
{
  "type": "<type>",
  "client": {
    "name": "<name>"
  },
  "currency": "<currency>",
  "docValueDate": "<docValueDate>",
  "dueDate": "<dueDate>",
  "title": "<title>",
  "docLang": "<docLang>",
  "items": [],
  "bankDetails": {},
  "subTotal": 0,
  "discount": 0,
  "totalWithoutVatAmount": 0,
  "vatAmount": 0,
  "totalAmount": 0,
  "totalPaid": 0,
  "originTaxDeduction": 0,
  "comment": "<comment>",
  "paymentCash": {
    "date": "<date>",
    "amount": 0
  },
  "paymentCreditCard": {
    "date": "<date>",
    "amount": 0
  },
  "paymentBankTransfer": {
    "date": "<date>",
    "amount": 0
  },
  "paymentCheque": {
    "date": "<date>",
    "receivedDate": "<receivedDate>",
    "amount": 0,
    "chequeNumber": "<chequeNumber>"
  },
  "paymentEWallet": {
    "date": "<date>",
    "amount": 0,
    "walletType": "<walletType>"
  },
  "payment": {},
  "callbacks": {}
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/seller/api/documents/income/preview' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "type": "<type>",
  "client": {
    "name": "<name>"
  },
  "currency": "<currency>",
  "docValueDate": "<docValueDate>",
  "docLang": "<docLang>",
  "items": [],
  "totalAmount": 0
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/seller/api/documents/income/preview", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "type": "<type>",
    "client": {
      "name": "<name>"
    },
    "currency": "<currency>",
    "docValueDate": "<docValueDate>",
    "docLang": "<docLang>",
    "items": [],
    "totalAmount": 0
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/seller/api/documents/income/preview",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "type": "<type>",
        "client": {
            "name": "<name>",
        },
        "currency": "<currency>",
        "docValueDate": "<docValueDate>",
        "docLang": "<docLang>",
        "items": [],
        "totalAmount": 0,
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "type": "<type>",
  "client": {
    "name": "<name>"
  },
  "currency": "<currency>",
  "docValueDate": "<docValueDate>",
  "docLang": "<docLang>",
  "items": [],
  "totalAmount": 0
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/seller/api/documents/income/preview');
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

### 200 — Preview generated successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `previewUrl` | string | URL to preview the document (temporary) |

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


## Partners API

- [Obtain access token](https://docs-staging.payme.io/keep/partners-api/gettoken): POST /oauth2/token — Obtain access token

# Obtain access token

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

## Credentials

- Request body field `client_secret` (required): Your client secret
- Request body field `refresh_token` (optional): Required when grant_type is refresh_token

Use this endpoint to obtain an access token using Client Credentials or to refresh an existing token.

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/x-www-form-urlencoded`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `grant_type` | string | yes | The grant type |
| `scope` | string | no | Space-separated scopes |
| `client_id` | string | yes | Your client ID |
| `client_secret` | string | yes | Your client secret |
| `refresh_token` | string | no | Required when grant_type is refresh_token |

### Request example

```json
{
  "grant_type": "client_credentials",
  "scope": "partner-api",
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/oauth2/token' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=partner-api' \
  --data-urlencode 'client_id=your-client-id' \
  --data-urlencode 'client_secret=your-client-secret'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/oauth2/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    "grant_type": "client_credentials",
    "scope": "partner-api",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/oauth2/token",
    data={
        "grant_type": "client_credentials",
        "scope": "partner-api",
        "client_id": "your-client-id",
        "client_secret": "your-client-secret",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/oauth2/token');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/x-www-form-urlencoded',
    ],
    CURLOPT_POSTFIELDS => http_build_query([
        'grant_type' => 'client_credentials',
        'scope' => 'partner-api',
        'client_id' => 'your-client-id',
        'client_secret' => 'your-client-secret',
    ]),
]);

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

echo $response;
```

## Responses

### 200 — Successful authentication (success)

| Field | Type | Description |
| --- | --- | --- |
| `token_type` | string |  |
| `access_token` | string | JWT access token |
| `refresh_token` | string | Refresh token |
| `expires_in` | integer | Access token lifetime in seconds |
| `refresh_expires_in` | integer | Refresh token lifetime in seconds |
| `scope` | string | Granted scopes |

### 401 — Unauthorized (error)

| Field | Type | Description |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

- [Create seller](https://docs-staging.payme.io/keep/partners-api/createseller): POST /public/sellers/create — Create seller

# Create seller

- Sandbox: `POST https://sandbox.payme.io/api/public/sellers/create`
- Production: `POST https://live.payme.io/api/public/sellers/create`

## Credentials

- Header `Authorization: Bearer <token>`

Register a new seller account with Israeli business compliance validation. Includes validation for Israeli ID numbers, business registration, and bank account details.

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `firstName` | string | yes | Seller's first name |
| `lastName` | string | yes | Seller's last name |
| `email` | string | yes | Seller's primary email address (used for login) |
| `contactEmail` | string | no | Business contact email address |
| `password` | string | yes | Account password |
| `phone` | string | yes | Phone number in international format |
| `businessName` | string | yes | Legal business name |
| `businessType` | integer | yes | Israeli business type classification |
| `businessNumber` | string | yes | Israeli business registration number (ח.פ. / עוסק מורשה) |
| `socialId` | string | yes | Israeli ID number (תעודת זהות) |
| `industryClassification` | string | no | Industry classification code (optional) |
| `bankId` | string | no | Israeli bank code (optional) |
| `accountNumber` | string | no | Bank account number (optional) |
| `branchNumber` | string | no | Bank branch number (optional) |
| `logo` | string | no | Business logo as base64 encoded data URI (optional) |

### Request example

```json
{
  "firstName": "David",
  "lastName": "Cohen",
  "email": "david.cohen@example.com",
  "contactEmail": "business@cohenelectronics.co.il",
  "password": "securePassword123",
  "phone": "0500000009",
  "businessName": "Cohen Electronics Ltd",
  "businessType": 1,
  "businessNumber": "330988015",
  "socialId": "336907282",
  "industryClassification": "12",
  "bankId": "12",
  "accountNumber": "123456789012345",
  "branchNumber": "123",
  "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/public/sellers/create' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "firstName": "David",
  "lastName": "Cohen",
  "email": "david.cohen@example.com",
  "contactEmail": "business@cohenelectronics.co.il",
  "password": "securePassword123",
  "phone": "0500000009",
  "businessName": "Cohen Electronics Ltd",
  "businessType": 1,
  "businessNumber": "330988015",
  "socialId": "336907282",
  "industryClassification": "12",
  "bankId": "12",
  "accountNumber": "123456789012345",
  "branchNumber": "123",
  "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/public/sellers/create", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "firstName": "David",
    "lastName": "Cohen",
    "email": "david.cohen@example.com",
    "contactEmail": "business@cohenelectronics.co.il",
    "password": "securePassword123",
    "phone": "0500000009",
    "businessName": "Cohen Electronics Ltd",
    "businessType": 1,
    "businessNumber": "330988015",
    "socialId": "336907282",
    "industryClassification": "12",
    "bankId": "12",
    "accountNumber": "123456789012345",
    "branchNumber": "123",
    "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/public/sellers/create",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "firstName": "David",
        "lastName": "Cohen",
        "email": "david.cohen@example.com",
        "contactEmail": "business@cohenelectronics.co.il",
        "password": "securePassword123",
        "phone": "0500000009",
        "businessName": "Cohen Electronics Ltd",
        "businessType": 1,
        "businessNumber": "330988015",
        "socialId": "336907282",
        "industryClassification": "12",
        "bankId": "12",
        "accountNumber": "123456789012345",
        "branchNumber": "123",
        "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "firstName": "David",
  "lastName": "Cohen",
  "email": "david.cohen@example.com",
  "contactEmail": "business@cohenelectronics.co.il",
  "password": "securePassword123",
  "phone": "0500000009",
  "businessName": "Cohen Electronics Ltd",
  "businessType": 1,
  "businessNumber": "330988015",
  "socialId": "336907282",
  "industryClassification": "12",
  "bankId": "12",
  "accountNumber": "123456789012345",
  "branchNumber": "123",
  "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/public/sellers/create');
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

### 201 — Seller created successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `payload` | object |  |
| `payload.sellerId` | string | Newly created seller's UUID |

```json
{
  "payload": {
    "sellerId": "9a5e7898-067e-4c0c-a50f-5f8d83e7c686"
  }
}
```

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [Get seller](https://docs-staging.payme.io/keep/partners-api/getsellerbyid): GET /public/sellers/{sellerId} — Get seller

# Get seller

- Sandbox: `GET https://sandbox.payme.io/api/public/sellers/{sellerId}`
- Production: `GET https://live.payme.io/api/public/sellers/{sellerId}`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve seller information by UUID. Returns seller details including business information and timestamps.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sellerId` | path | string | yes | Seller UUID |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/public/sellers/<sellerId>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/public/sellers/<sellerId>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/public/sellers/<sellerId>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/public/sellers/<sellerId>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Seller retrieved successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `payload` | object |  |
| `payload.id` | string | Seller UUID |
| `payload.firstName` | string | Seller's first name |
| `payload.lastName` | string | Seller's last name |
| `payload.email` | string | Primary email address |
| `payload.contactEmail` | string | Business contact email |
| `payload.phone` | string | Phone number |
| `payload.businessName` | string | Legal business name |
| `payload.businessType` | integer | Israeli business type classification |
| `payload.businessNumber` | string | Israeli business registration number |
| `payload.socialId` | string | Israeli ID number |
| `payload.createdAt` | string | Account creation timestamp |
| `payload.updatedAt` | string | Last update timestamp |

```json
{
  "payload": {
    "id": "97bdce55-b2a2-450d-8d29-1dcf6bbcc419",
    "firstName": "David",
    "lastName": "Cohen",
    "email": "david.cohen@example.com",
    "contactEmail": "business@cohenelectronics.co.il",
    "phone": "0500000009",
    "businessName": "Cohen Electronics Ltd",
    "businessType": 1,
    "businessNumber": "330988015",
    "socialId": "336907282",
    "createdAt": "2026-01-22T09:19:54.264Z",
    "updatedAt": "2026-01-22T09:19:54.403Z"
  }
}
```

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

### 404 — Seller not found (error)

- [Get available plans](https://docs-staging.payme.io/keep/partners-api/getpartnerplans): GET /public/plans — Get available plans

# Get available plans

- Sandbox: `GET https://sandbox.payme.io/api/public/plans`
- Production: `GET https://live.payme.io/api/public/plans`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve all available plans for the authenticated partner. Free trial and No Cost plans are excluded.

## Parameters

This endpoint takes no path, query or header parameters.

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/public/plans' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/public/plans", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/public/plans",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/public/plans');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Plans retrieved successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `payload` | object |  |
| `payload.items` | array |  |
| `payload.items[].id` | string | Unique identifier for the plan |
| `payload.items[].name` | string | Display name of the plan |
| `payload.items[].price` | number | Plan price in the partner's currency |

```json
{
  "payload": {
    "items": [
      {
        "id": "90abd0eb-c374-4a2b-829e-681fba0cdbee",
        "name": "PaturBasic",
        "price": 39.9
      },
      {
        "id": "29b1f228-c779-4de3-bb99-aa8e34f29ddc",
        "name": "PaturPremium",
        "price": 105
      },
      {
        "id": "3d653770-6376-40a5-b98e-17c598f1d7d8",
        "name": "MursheBasic",
        "price": 39.9
      },
      {
        "id": "c2249657-fe98-49ae-950a-3bdf28cdbfee",
        "name": "MurshePremium",
        "price": 228
      }
    ]
  }
}
```

### 401 — Unauthorized (error)

| Field | Type | Description |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [List expenses](https://docs-staging.payme.io/keep/partners-api/listpublicexpenses): GET /public/expenses — List expenses

# List expenses

- Sandbox: `GET https://sandbox.payme.io/api/public/expenses`
- Production: `GET https://live.payme.io/api/public/expenses`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve expense records for a seller with optional date filtering and pagination.

**Seller identification:** Same rules as the upload endpoint — provide `sellerId` alone, or `socialId` + `email`.

**Date filtering:** `valueDateStart` and `valueDateEnd` filter on the expense value date (not creation date). Dates must be ISO format (`YYYY-MM-DD`) and `valueDateStart` must be ≤ `valueDateEnd`.

**Pagination:** Defaults to `page=0`, `limit=10`. Maximum `limit=500`.

Expenses not found are silently omitted. Order of returned items is not guaranteed.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sellerId` | query | string | no | Seller UUID (use this OR socialId + email) |
| `socialId` | query | string | no | Seller social/business ID number (must be paired with email) |
| `email` | query | string | no | Seller email address (must be paired with socialId) |
| `valueDateStart` | query | string | no | Filter expenses from this value date (inclusive, YYYY-MM-DD) |
| `valueDateEnd` | query | string | no | Filter expenses up to this value date (inclusive, YYYY-MM-DD) |
| `page` | query | integer | no | Page number (zero-based) |
| `limit` | query | integer | no | Items per page |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/public/expenses' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/public/expenses", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/public/expenses",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/public/expenses');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Expenses retrieved successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `payload` | object |  |
| `payload.total` | integer | Total number of matching expenses |
| `payload.page` | integer | Current page number |
| `payload.limit` | integer | Items per page |
| `payload.items` | array |  |
| `payload.items[].id` | string | Expense record UUID |
| `payload.items[].capturedDate` | string | Timestamp when the expense was captured |
| `payload.items[].valueDate` | string | Expense value date |
| `payload.items[].sellerId` | string | Seller UUID |
| `payload.items[].totalAmount` | number | Total expense amount |
| `payload.items[].vatAmount` | number | VAT amount |
| `payload.items[].currency` | string | Currency code |
| `payload.items[].bookkeeperRevisionStatus` | string | Bookkeeper revision status |
| `payload.items[].docRegulationId` | string | Document regulation ID |
| `payload.items[].docType` | string | Document type |

```json
{
  "payload": {
    "total": 1,
    "page": 0,
    "limit": 10,
    "items": [
      {
        "id": "50c6b740-874a-4f54-9669-9a60024be4ed",
        "capturedDate": "2024-06-20T09:35:36.326Z",
        "valueDate": "2024-06-20T00:00:00.000Z",
        "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
        "totalAmount": 15200,
        "vatAmount": 2209,
        "currency": "ILS",
        "bookkeeperRevisionStatus": "approved-and-classified",
        "docRegulationId": "1262",
        "docType": "invrec"
      }
    ]
  }
}
```

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

### 422 — Unprocessable Entity (error)

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

```json
{
  "statusCode": 422,
  "message": "Bad seller configuration. Please contact support!",
  "error": "Unprocessable Entity"
}
```

- [Upload expense document](https://docs-staging.payme.io/keep/partners-api/uploadpublicexpense): POST /public/expenses — Upload expense document

# Upload expense document

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

## Credentials

- Header `Authorization: Bearer <token>`

Upload an expense document for a seller via a publicly accessible file URL.

**Seller identification:** Exactly one method must be used per request:
- **Option A:** `sellerId` (UUID)
- **Option B:** `socialId` + `email`

Providing both or neither returns HTTP 400.

**Supported file formats:** PDF, JPG, PNG.

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sellerId` | string | no | Seller UUID (use this OR socialId + email, not both) |
| `socialId` | string | no | Seller social/business ID number (must be paired with email) |
| `email` | string | no | Seller email address (must be paired with socialId) |
| `file` | string | yes | Publicly accessible URL of the expense document (PDF, JPG, or PNG) |

### Request example

```json
{
  "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
  "file": "https://i0.wp.com/avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/AK-3.png?ssl=1"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/public/expenses' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
  "file": "https://i0.wp.com/avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/AK-3.png?ssl=1"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/public/expenses", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
    "file": "https://i0.wp.com/avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/AK-3.png?ssl=1"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/public/expenses",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
        "file": "https://i0.wp.com/avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/AK-3.png?ssl=1",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
  "file": "https://i0.wp.com/avatar-management--avatars.us-west-2.prod.public.atl-paas.net/initials/AK-3.png?ssl=1"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/public/expenses');
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

### 200 — Expense document uploaded successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `payload` | object |  |
| `payload.id` | string | Unique identifier for the created expense record |
| `payload.capturedDate` | string | Timestamp when the expense was captured |
| `payload.sellerId` | string | Resolved seller UUID |

```json
{
  "payload": {
    "id": "a3504d9d-c187-48a0-8274-bea3b48e5663",
    "capturedDate": "2026-02-02T13:05:54.170Z",
    "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982"
  }
}
```

### 400 — Validation error (error)

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

```json
{
  "statusCode": 400,
  "message": [
    "socialId must be a number conforming to the specified constraints",
    "socialId should not be empty",
    "email must be an email",
    "email should not be empty",
    "sellerId must be a UUID",
    "sellerId should not be empty"
  ],
  "error": "Bad Request"
}
```

### 401 — Unauthorized (error)

| Field | Type | Description |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

### 422 — Unprocessable entity — seller not resolved or file URL unreachable (error)

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

```json
{
  "statusCode": 422,
  "message": "Could not resolve seller",
  "error": "Unprocessable Entity"
}
```

- [Update expense](https://docs-staging.payme.io/keep/partners-api/updatepublicexpense): PATCH /public/expenses/{expenseId} — Update expense

# Update expense

- Sandbox: `PATCH https://sandbox.payme.io/api/public/expenses/{expenseId}`
- Production: `PATCH https://live.payme.io/api/public/expenses/{expenseId}`

## Credentials

- Header `Authorization: Bearer <token>`

Partially update an existing expense document. Only expenses with `pending` status can be updated.

The partner can only update expenses within their own scope, and the expense must belong to the provided `sellerId`.

**Immutable fields** (rejected if provided): `id`, `uid`, `partnerId`, `createdAt`, `updatedAt`, `updatedBy`, `seller`, `supplierSnapshot`, `vatReportSnapshot`, `isAbleToAutoApprove`, `status`.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `expenseId` | path | string | yes | Expense UUID to update |

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sellerId` | string | no | Seller UUID the expense belongs to |
| `valueDate` | string | no | Expense value date (ISO 8601 UTC) |
| `totalAmount` | number | no | Total expense amount |
| `vatAmount` | number | no | VAT amount (must be ≤ totalAmount) |
| `currency` | string | no | Currency code |
| `captureMethod` | string | no | How the expense was captured (e.g., 'manual') |
| `docType` | string | no | Document type |
| `docRegulationId` | string | no | Document regulation ID |
| `docLocatorNumber` | string | no | Document locator number |
| `classification` | integer | no | Classification ID (must be valid for seller/partner context) |
| `deductibleIncomeTaxPercent` | integer | no | Deductible income tax percentage (0–100) |
| `deductibleVatPercent` | integer | no | Deductible VAT percentage (0–100) |
| `assetVatRefundPercent` | integer | no | Asset VAT refund percentage (0–100) |
| `comment` | string | no | Optional partner note |
| `supplierName` | string | no | Supplier name |
| `supplierVatId` | string | no | Supplier VAT ID |
| `vatAllocationNumber` | string | no | VAT allocation number (nullable) |
| `isExcludeFromPCN` | boolean | no | Whether to exclude from PCN report |

### Request example

```json
{
  "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
  "valueDate": "2025-10-28T00:00:00.000Z",
  "totalAmount": 15000,
  "vatAmount": 2288,
  "currency": "ILS",
  "captureMethod": "manual",
  "docType": "invrec",
  "docRegulationId": "5132277",
  "docLocatorNumber": "85712",
  "classification": 6,
  "deductibleIncomeTaxPercent": 100,
  "deductibleVatPercent": 100,
  "assetVatRefundPercent": 0,
  "comment": "Optional partner note",
  "supplierName": "Supplier Ltd",
  "supplierVatId": "123456789",
  "vatAllocationNumber": null,
  "isExcludeFromPCN": false
}
```

## Code samples

### curl

```bash
curl -X PATCH 'https://sandbox.payme.io/api/public/expenses/<expenseId>' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
  "valueDate": "2025-10-28T00:00:00.000Z",
  "totalAmount": 15000,
  "vatAmount": 2288,
  "currency": "ILS",
  "captureMethod": "manual",
  "docType": "invrec",
  "docRegulationId": "5132277",
  "docLocatorNumber": "85712",
  "classification": 6,
  "deductibleIncomeTaxPercent": 100,
  "deductibleVatPercent": 100,
  "assetVatRefundPercent": 0,
  "comment": "Optional partner note",
  "supplierName": "Supplier Ltd",
  "supplierVatId": "123456789",
  "vatAllocationNumber": null,
  "isExcludeFromPCN": false
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/public/expenses/<expenseId>", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
    "valueDate": "2025-10-28T00:00:00.000Z",
    "totalAmount": 15000,
    "vatAmount": 2288,
    "currency": "ILS",
    "captureMethod": "manual",
    "docType": "invrec",
    "docRegulationId": "5132277",
    "docLocatorNumber": "85712",
    "classification": 6,
    "deductibleIncomeTaxPercent": 100,
    "deductibleVatPercent": 100,
    "assetVatRefundPercent": 0,
    "comment": "Optional partner note",
    "supplierName": "Supplier Ltd",
    "supplierVatId": "123456789",
    "vatAllocationNumber": null,
    "isExcludeFromPCN": false
  }),
});

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

### Python

```python
import requests

response = requests.patch(
    "https://sandbox.payme.io/api/public/expenses/<expenseId>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
        "valueDate": "2025-10-28T00:00:00.000Z",
        "totalAmount": 15000,
        "vatAmount": 2288,
        "currency": "ILS",
        "captureMethod": "manual",
        "docType": "invrec",
        "docRegulationId": "5132277",
        "docLocatorNumber": "85712",
        "classification": 6,
        "deductibleIncomeTaxPercent": 100,
        "deductibleVatPercent": 100,
        "assetVatRefundPercent": 0,
        "comment": "Optional partner note",
        "supplierName": "Supplier Ltd",
        "supplierVatId": "123456789",
        "vatAllocationNumber": None,
        "isExcludeFromPCN": False,
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
  "valueDate": "2025-10-28T00:00:00.000Z",
  "totalAmount": 15000,
  "vatAmount": 2288,
  "currency": "ILS",
  "captureMethod": "manual",
  "docType": "invrec",
  "docRegulationId": "5132277",
  "docLocatorNumber": "85712",
  "classification": 6,
  "deductibleIncomeTaxPercent": 100,
  "deductibleVatPercent": 100,
  "assetVatRefundPercent": 0,
  "comment": "Optional partner note",
  "supplierName": "Supplier Ltd",
  "supplierVatId": "123456789",
  "vatAllocationNumber": null,
  "isExcludeFromPCN": false
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/public/expenses/<expenseId>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PATCH',
    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

### 200 — Expense updated successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | 0 for success |
| `payload` | object |  |
| `payload.expenseId` | string | Expense UUID |
| `payload.sellerId` | string | Seller UUID |
| `payload.valueDate` | string | Expense value date |
| `payload.totalAmount` | number | Total expense amount |
| `payload.vatAmount` | number | VAT amount |
| `payload.currency` | string | Currency code |
| `payload.docType` | string | Document type |
| `payload.docRegulationId` | string | Document regulation ID |
| `payload.docLocatorNumber` | string | Document locator number |
| `payload.classification` | integer | Classification ID |
| `payload.capturedDate` | string | Timestamp when expense was captured |
| `payload.updatedAt` | string | Last update timestamp |

```json
{
  "statusCode": 0,
  "payload": {
    "expenseId": "edc855f7-cb7c-4d82-8c26-baf5c296d391",
    "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
    "valueDate": "2025-10-28T00:00:00.000Z",
    "totalAmount": 15000,
    "vatAmount": 2288,
    "currency": "ILS",
    "docType": "invrec",
    "docRegulationId": "5132277",
    "docLocatorNumber": "85712",
    "classification": 6,
    "capturedDate": "2025-10-28T09:13:37.423Z",
    "updatedAt": "2025-10-28T09:16:33.795Z"
  }
}
```

### 400 — Validation error (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | 1 for error |
| `payload` | object |  |
| `payload.message` | string | Error message |
| `payload.additionalInfo` | object | Field-level validation details |

```json
{
  "statusCode": 1,
  "payload": {
    "message": "Invalid request",
    "additionalInfo": {
      "valueDate": "Must be a valid ISO datetime",
      "totalAmount": "Must be >= 0"
    }
  }
}
```

### 401 — Unauthorized (error)

| Field | Type | Description |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

### 403 — Partner is not authorized to update this expense (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | 1 for error |
| `payload` | object |  |
| `payload.message` | string | Error message |
| `payload.additionalInfo` | object | Field-level validation details |

```json
{
  "statusCode": 1,
  "payload": {
    "message": "Not allowed"
  }
}
```

### 404 — Expense or seller not found (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | 1 for error |
| `payload` | object |  |
| `payload.message` | string | Error message |
| `payload.additionalInfo` | object | Field-level validation details |

```json
{
  "statusCode": 1,
  "payload": {
    "message": "Expense not found"
  }
}
```

### 409 — Update conflict (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | 1 for error |
| `payload` | object |  |
| `payload.message` | string | Error message |
| `payload.additionalInfo` | object | Field-level validation details |

```json
{
  "statusCode": 1,
  "payload": {
    "message": "Update conflict"
  }
}
```

### 429 — Rate limit exceeded (error)

| Field | Type | Description |
| --- | --- | --- |
| `statusCode` | integer | 1 for error |
| `payload` | object |  |
| `payload.message` | string | Error message |
| `payload.additionalInfo` | object | Field-level validation details |

```json
{
  "statusCode": 1,
  "payload": {
    "message": "Rate limit exceeded"
  }
}
```

- [Update seller](https://docs-staging.payme.io/keep/partners-api/updatesellerbyid): PUT /public/sellers/{sellerId}/update — Update seller

# Update seller

- Sandbox: `PUT https://sandbox.payme.io/api/public/sellers/{sellerId}/update`
- Production: `PUT https://live.payme.io/api/public/sellers/{sellerId}/update`

## Credentials

- Header `Authorization: Bearer <token>`

Update existing seller details. Supports partial updates with Israeli compliance re-validation for modified fields.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sellerId` | path | string | yes | Seller UUID |

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `firstName` | string | no | Seller's first name |
| `lastName` | string | no | Seller's last name |
| `email` | string | no | Primary email address |
| `contactEmail` | string | no | Business contact email |
| `phone` | string | no | Phone number in international format |
| `businessName` | string | no | Legal business name |
| `businessType` | integer | no | Israeli business type classification |
| `businessNumber` | string | no | Israeli business registration number |
| `socialId` | string | no | Israeli ID number |
| `bankId` | string | no | Israeli bank code |
| `accountNumber` | string | no | Bank account number |
| `branchNumber` | string | no | Bank branch number |
| `logo` | string | no | Business logo as base64 encoded data URI |

### Request example

```json
{
  "firstName": "David",
  "lastName": "Cohen",
  "email": "david.cohen1115@example.com",
  "contactEmail": "business@cohenelectronics.co.il",
  "phone": "0500000008",
  "businessName": "Cohen Electronics",
  "businessType": 2,
  "businessNumber": "330988015",
  "socialId": "336907282",
  "bankId": "12",
  "accountNumber": "123456789012345",
  "branchNumber": "123",
  "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
```

## Code samples

### curl

```bash
curl -X PUT 'https://sandbox.payme.io/api/public/sellers/<sellerId>/update' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "firstName": "David",
  "lastName": "Cohen",
  "email": "david.cohen1115@example.com",
  "contactEmail": "business@cohenelectronics.co.il",
  "phone": "0500000008",
  "businessName": "Cohen Electronics",
  "businessType": 2,
  "businessNumber": "330988015",
  "socialId": "336907282",
  "bankId": "12",
  "accountNumber": "123456789012345",
  "branchNumber": "123",
  "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/public/sellers/<sellerId>/update", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "firstName": "David",
    "lastName": "Cohen",
    "email": "david.cohen1115@example.com",
    "contactEmail": "business@cohenelectronics.co.il",
    "phone": "0500000008",
    "businessName": "Cohen Electronics",
    "businessType": 2,
    "businessNumber": "330988015",
    "socialId": "336907282",
    "bankId": "12",
    "accountNumber": "123456789012345",
    "branchNumber": "123",
    "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }),
});

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

### Python

```python
import requests

response = requests.put(
    "https://sandbox.payme.io/api/public/sellers/<sellerId>/update",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "firstName": "David",
        "lastName": "Cohen",
        "email": "david.cohen1115@example.com",
        "contactEmail": "business@cohenelectronics.co.il",
        "phone": "0500000008",
        "businessName": "Cohen Electronics",
        "businessType": 2,
        "businessNumber": "330988015",
        "socialId": "336907282",
        "bankId": "12",
        "accountNumber": "123456789012345",
        "branchNumber": "123",
        "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "firstName": "David",
  "lastName": "Cohen",
  "email": "david.cohen1115@example.com",
  "contactEmail": "business@cohenelectronics.co.il",
  "phone": "0500000008",
  "businessName": "Cohen Electronics",
  "businessType": 2,
  "businessNumber": "330988015",
  "socialId": "336907282",
  "bankId": "12",
  "accountNumber": "123456789012345",
  "branchNumber": "123",
  "logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/public/sellers/<sellerId>/update');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    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

### 200 — Seller updated successfully (success)

```json
{}
```

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

### 404 — Seller not found (error)

- [Get external URLs for seller](https://docs-staging.payme.io/keep/partners-api/getsellerexternalurls): GET /partner/api/sellers/external-urls — Get external URLs for seller

# Get external URLs for seller

- Sandbox: `GET https://sandbox.payme.io/api/partner/api/sellers/external-urls`
- Production: `GET https://live.payme.io/api/partner/api/sellers/external-urls`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve external URLs for a seller by ID, social ID, or email

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | query | string | no | Seller ID (MPL format) |
| `socialId` | query | string | no | Seller social/business ID number |
| `email` | query | string | no | Seller email address |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/partner/api/sellers/external-urls' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/sellers/external-urls", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/partner/api/sellers/external-urls",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/partner/api/sellers/external-urls');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Successful response (success)

| Field | Type | Description |
| --- | --- | --- |
| `creditCardUrl` | string |  |
| `financeProfileUrl` | string |  |
| `paymentsOnboardingUrl` | string |  |
| `documentsUploadUrl` | string |  |

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [Get finance profile URL](https://docs-staging.payme.io/keep/partners-api/getsellerfinanceprofile): GET /partner/api/sellers/finance-profile — Get finance profile URL

# Get finance profile URL

- Sandbox: `GET https://sandbox.payme.io/api/partner/api/sellers/finance-profile`
- Production: `GET https://live.payme.io/api/partner/api/sellers/finance-profile`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve the finance profile URL for a seller

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | query | string | no | Seller ID (MPL format) |
| `socialId` | query | string | no | Seller social/business ID number |
| `email` | query | string | no | Seller email address |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/partner/api/sellers/finance-profile' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/sellers/finance-profile", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/partner/api/sellers/finance-profile",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/partner/api/sellers/finance-profile');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Successful response (success)

| Field | Type | Description |
| --- | --- | --- |
| `url` | string |  |

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [Set seller billing plan](https://docs-staging.payme.io/keep/partners-api/setsellerplan): POST /partner/api/sellers/set-plan — Set seller billing plan

# Set seller billing plan

- Sandbox: `POST https://sandbox.payme.io/api/partner/api/sellers/set-plan`
- Production: `POST https://live.payme.io/api/partner/api/sellers/set-plan`

## Credentials

- Header `Authorization: Bearer <token>`

Assign a billing plan to a seller with payer-based activation flow.

**Payer modes:**
- `partner` — Plan is activated immediately (no credit card required).
- `seller` — If the seller already has a credit card on file, the plan is activated immediately. If not, a credit card URL is returned and the plan activates once the seller completes payment.

> **Note:** `callBackUrl` is not yet implemented and will be ignored.

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sellerId` | string | yes | Seller identifier (UUID, MPL ID, email, or socialId) |
| `planId` | string | yes | Plan identifier to assign |
| `payer` | string | yes | Who pays for the plan. 'partner' = immediate activation, 'seller' = may require credit card. |

### Request example

```json
{
  "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
  "planId": "3d653770-6376-40a5-b98e-17c598f1d7d8",
  "payer": "partner"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/partner/api/sellers/set-plan' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
  "planId": "3d653770-6376-40a5-b98e-17c598f1d7d8",
  "payer": "partner"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/sellers/set-plan", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
    "planId": "3d653770-6376-40a5-b98e-17c598f1d7d8",
    "payer": "partner"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/partner/api/sellers/set-plan",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
        "planId": "3d653770-6376-40a5-b98e-17c598f1d7d8",
        "payer": "partner",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "sellerId": "a6a9700f-8571-4f9b-bfae-ba943fb96982",
  "planId": "3d653770-6376-40a5-b98e-17c598f1d7d8",
  "payer": "partner"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/partner/api/sellers/set-plan');
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

### 200 — Plan set successfully (success)

| Field | Type | Description |
| --- | --- | --- |
| `payload` | object |  |
| `payload.status` | string | 'activated' when plan is active immediately, 'pending' when seller must complete payment first. |
| `payload.message` | string | Human-readable message (present when status is 'pending') |
| `payload.creditCardUrl` | string | URL for seller to submit credit card details (present when status is 'pending') |

```json
{
  "payload": {
    "status": "activated"
  }
}
```

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

### 404 — Seller or plan not found (error)

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

```json
{
  "statusCode": 404,
  "message": "Seller not found",
  "error": "Not Found"
}
```

### 422 — Unprocessable Entity (error)

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

```json
{
  "statusCode": 422,
  "message": "Bad seller configuration. Please contact support!",
  "error": "Unprocessable Entity"
}
```

- [Create seller comment](https://docs-staging.payme.io/keep/partners-api/createsellercomment): POST /partner/api/sellers/comment — Create seller comment

# Create seller comment

- Sandbox: `POST https://sandbox.payme.io/api/partner/api/sellers/comment`
- Production: `POST https://live.payme.io/api/partner/api/sellers/comment`

## Credentials

- Header `Authorization: Bearer <token>`

Add a comment to a seller's record

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sellerId` | string | yes | Seller ID |
| `commentCategory` | string | no | Comment category |
| `commentText` | string | yes | Comment text |

### Request example

No example is documented; this template is generated from the fields — replace the placeholder values.

```json
{
  "sellerId": "<sellerId>",
  "commentCategory": "<commentCategory>",
  "commentText": "<commentText>"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/partner/api/sellers/comment' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "sellerId": "<sellerId>",
  "commentText": "<commentText>"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/sellers/comment", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "sellerId": "<sellerId>",
    "commentText": "<commentText>"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/partner/api/sellers/comment",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "sellerId": "<sellerId>",
        "commentText": "<commentText>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "sellerId": "<sellerId>",
  "commentText": "<commentText>"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/partner/api/sellers/comment');
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

### 201 — Comment created successfully (success)

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [List income documents](https://docs-staging.payme.io/keep/partners-api/listincomedocuments): GET /partner/api/documents/income — List income documents

# List income documents

- Sandbox: `GET https://sandbox.payme.io/api/partner/api/documents/income`
- Production: `GET https://live.payme.io/api/partner/api/documents/income`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve a list of income documents for a seller

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `sellerPaymeId` | query | string | no | Seller PayMe ID |
| `sellerId` | query | string | no | Seller ID |
| `docNum` | query | string | no | Document number filter |
| `page` | query | integer | no | Page number |
| `limit` | query | integer | no | Items per page |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/partner/api/documents/income' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/documents/income", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/partner/api/documents/income",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/partner/api/documents/income');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Successful response (success)

| Field | Type | Description |
| --- | --- | --- |
| `payload` | object |  |
| `payload.page` | integer |  |
| `payload.limit` | integer |  |
| `payload.total` | integer |  |
| `payload.items` | array |  |
| `payload.items[].id` | string |  |
| `payload.items[].docType` | string |  |
| `payload.items[].docNumber` | string |  |
| `payload.items[].valueDate` | string |  |
| `payload.items[].totalAmount` | number |  |
| `payload.items[].vatAmount` | number |  |
| `payload.items[].currency` | string |  |
| `payload.items[].status` | string |  |

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [Create manual income document](https://docs-staging.payme.io/keep/partners-api/createmanualincomedocument): POST /partner/api/documents/income/manual — Create manual income document

# Create manual income document

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

## Credentials

- Header `Authorization: Bearer <token>`

Create a new income document manually

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_email` | string | no | Seller's email address |
| `seller_social_id_number` | string | no | Seller's social/business ID number |
| `doc_type` | string | yes | Document type |
| `value_date` | string | yes | Document value date |
| `due_date` | string | no | Payment due date (required for invoice, deal, offer) |
| `currency` | string | yes | Document currency |
| `doc_language` | string | yes | Document language |
| `client_name` | string | no | Client/customer name |
| `client_email` | string | no | Client email |
| `client_phone` | string | no | Client phone |
| `items` | array | yes | Document line items |
| `items[].name` | string | yes | Item name |
| `items[].quantity` | number | yes | Item quantity |
| `items[].item_net_price` | number | yes | Item net price (before VAT) |
| `items[].item_currency` | string | yes | Item currency |
| `items[].item_total_price` | number | no | Item total price |
| `items[].is_no_item_vat` | boolean | no | VAT exempt flag (true = no VAT) |
| `total_amount` | number | yes | Total amount including VAT |
| `vat_amount` | number | no | VAT amount |
| `total_without_vat` | number | no | Total amount without VAT |
| `discount` | number | no | Discount amount |
| `comment` | string | no | Document comments |
| `origin_tax_deduction` | number | no | Tax deduction at source |
| `callbacks` | object | no | Callback URLs for async notifications |
| `callbacks.success` | array | no | URLs to call on success |
| `callbacks.error` | array | no | URLs to call on error |
| `payment_cash` | object | no |  |
| `payment_cash.date` | string | yes | Payment date |
| `payment_cash.amount` | number | yes | Payment amount |
| `payment_credit_card` | object | no |  |
| `payment_credit_card.date` | string | yes | Payment date |
| `payment_credit_card.amount` | number | yes | Payment amount |
| `payment_credit_card.last4Digits` | string | no | Last 4 digits of card |
| `payment_bank_transfer` | object | no |  |
| `payment_bank_transfer.date` | string | yes | Payment date |
| `payment_bank_transfer.amount` | number | yes | Payment amount |
| `payment_bank_transfer.bankNumber` | integer | no | Bank code |
| `payment_bank_transfer.branchNumber` | integer | no | Branch number |
| `payment_bank_transfer.accountNumber` | integer | yes | Account number |
| `payment_cheque` | object | no |  |
| `payment_cheque.date` | string | yes | Payment date |
| `payment_cheque.receivedDate` | string | yes | Cheque received date |
| `payment_cheque.amount` | number | yes | Payment amount |
| `payment_cheque.chequeNumber` | number | yes | Cheque number |
| `payment_cheque.bankNumber` | integer | no | Bank code |
| `payment_cheque.branchNumber` | integer | no | Branch number |
| `payment_cheque.accountNumber` | integer | no | Account number |

### Request example

```json
{
  "seller_email": "seller@example.com",
  "seller_social_id_number": "123456789",
  "doc_type": "deal",
  "value_date": "2024-01-15 00:00:00",
  "currency": "ILS",
  "doc_language": "he",
  "client_name": "John Doe",
  "client_email": "john@example.com",
  "items": [
    {
      "name": "Service",
      "quantity": 1,
      "item_net_price": 1000,
      "item_currency": "ILS",
      "is_no_item_vat": false
    }
  ],
  "total_amount": 1170,
  "vat_amount": 170,
  "total_without_vat": 1000
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/partner/api/documents/income/manual' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "seller_email": "seller@example.com",
  "seller_social_id_number": "123456789",
  "doc_type": "deal",
  "value_date": "2024-01-15 00:00:00",
  "currency": "ILS",
  "doc_language": "he",
  "client_name": "John Doe",
  "client_email": "john@example.com",
  "items": [
    {
      "name": "Service",
      "quantity": 1,
      "item_net_price": 1000,
      "item_currency": "ILS",
      "is_no_item_vat": false
    }
  ],
  "total_amount": 1170,
  "vat_amount": 170,
  "total_without_vat": 1000
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/documents/income/manual", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "seller_email": "seller@example.com",
    "seller_social_id_number": "123456789",
    "doc_type": "deal",
    "value_date": "2024-01-15 00:00:00",
    "currency": "ILS",
    "doc_language": "he",
    "client_name": "John Doe",
    "client_email": "john@example.com",
    "items": [
      {
        "name": "Service",
        "quantity": 1,
        "item_net_price": 1000,
        "item_currency": "ILS",
        "is_no_item_vat": false
      }
    ],
    "total_amount": 1170,
    "vat_amount": 170,
    "total_without_vat": 1000
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/partner/api/documents/income/manual",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "seller_email": "seller@example.com",
        "seller_social_id_number": "123456789",
        "doc_type": "deal",
        "value_date": "2024-01-15 00:00:00",
        "currency": "ILS",
        "doc_language": "he",
        "client_name": "John Doe",
        "client_email": "john@example.com",
        "items": [
            {
                "name": "Service",
                "quantity": 1,
                "item_net_price": 1000,
                "item_currency": "ILS",
                "is_no_item_vat": False,
            },
        ],
        "total_amount": 1170,
        "vat_amount": 170,
        "total_without_vat": 1000,
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "seller_email": "seller@example.com",
  "seller_social_id_number": "123456789",
  "doc_type": "deal",
  "value_date": "2024-01-15 00:00:00",
  "currency": "ILS",
  "doc_language": "he",
  "client_name": "John Doe",
  "client_email": "john@example.com",
  "items": [
    {
      "name": "Service",
      "quantity": 1,
      "item_net_price": 1000,
      "item_currency": "ILS",
      "is_no_item_vat": false
    }
  ],
  "total_amount": 1170,
  "vat_amount": 170,
  "total_without_vat": 1000
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/partner/api/documents/income/manual');
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

### 201 — Document created (success)

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Document ID |
| `url` | string | Document URL |

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [Setup tax authority for seller](https://docs-staging.payme.io/keep/partners-api/setuptaxauthority): POST /partner/api/tax-authority/setup — Setup tax authority for seller

# Setup tax authority for seller

- Sandbox: `POST https://sandbox.payme.io/api/partner/api/tax-authority/setup`
- Production: `POST https://live.payme.io/api/partner/api/tax-authority/setup`

## Credentials

- Header `Authorization: Bearer <token>`

Configure tax authority integration for a seller

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_email` | string | yes | Seller email |
| `seller_id_number` | string | yes | Seller ID number |
| `osek_type` | string | yes | Business type (osek) |
| `file_name` | string | no | Authorization file name |
| `file_path` | string | no | Authorization file path |

### Request example

No example is documented; this template is generated from the fields — replace the placeholder values.

```json
{
  "seller_email": "<seller_email>",
  "seller_id_number": "<seller_id_number>",
  "osek_type": "<osek_type>",
  "file_name": "<file_name>",
  "file_path": "<file_path>"
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/partner/api/tax-authority/setup' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "seller_email": "<seller_email>",
  "seller_id_number": "<seller_id_number>",
  "osek_type": "<osek_type>"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/tax-authority/setup", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "seller_email": "<seller_email>",
    "seller_id_number": "<seller_id_number>",
    "osek_type": "<osek_type>"
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/partner/api/tax-authority/setup",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "seller_email": "<seller_email>",
        "seller_id_number": "<seller_id_number>",
        "osek_type": "<osek_type>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "seller_email": "<seller_email>",
  "seller_id_number": "<seller_id_number>",
  "osek_type": "<osek_type>"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/partner/api/tax-authority/setup');
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

### 200 — Tax authority setup successful (success)

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [Set VAT balance](https://docs-staging.payme.io/keep/partners-api/setvatbalance): POST /partner/api/sellers/vat-balance — Set VAT balance

# Set VAT balance

- Sandbox: `POST https://sandbox.payme.io/api/partner/api/sellers/vat-balance`
- Production: `POST https://live.payme.io/api/partner/api/sellers/vat-balance`

## Credentials

- Header `Authorization: Bearer <token>`

Set VAT balance for a seller

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `socialId` | string | no | Seller social ID |
| `email` | string | no | Seller email |
| `id` | string | no | Seller ID |
| `balance` | number | yes | Balance amount |
| `reportingYear` | integer | no | Reporting year |
| `reportingMonth` | integer | no | Reporting month |

### Request example

No example is documented; this template is generated from the fields — replace the placeholder values.

```json
{
  "socialId": "<socialId>",
  "email": "<email>",
  "id": "<id>",
  "balance": 0,
  "reportingYear": 0,
  "reportingMonth": 0
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/partner/api/sellers/vat-balance' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "balance": 0
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/sellers/vat-balance", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "balance": 0
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/partner/api/sellers/vat-balance",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "balance": 0,
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "balance": 0
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/partner/api/sellers/vat-balance');
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

### 200 — VAT balance updated (success)

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [Set tax balance](https://docs-staging.payme.io/keep/partners-api/settaxbalance): POST /partner/api/sellers/tax-balance — Set tax balance

# Set tax balance

- Sandbox: `POST https://sandbox.payme.io/api/partner/api/sellers/tax-balance`
- Production: `POST https://live.payme.io/api/partner/api/sellers/tax-balance`

## Credentials

- Header `Authorization: Bearer <token>`

Set tax balance for a seller

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `socialId` | string | no | Seller social ID |
| `email` | string | no | Seller email |
| `id` | string | no | Seller ID |
| `balance` | number | yes | Balance amount |
| `reportingYear` | integer | no | Reporting year |
| `reportingMonth` | integer | no | Reporting month |

### Request example

No example is documented; this template is generated from the fields — replace the placeholder values.

```json
{
  "socialId": "<socialId>",
  "email": "<email>",
  "id": "<id>",
  "balance": 0,
  "reportingYear": 0,
  "reportingMonth": 0
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/partner/api/sellers/tax-balance' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <YOUR_TOKEN>' \
  --data-raw '{
  "balance": 0
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/sellers/tax-balance", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
  body: JSON.stringify({
    "balance": 0
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/partner/api/sellers/tax-balance",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
    json={
        "balance": 0,
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "balance": 0
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/partner/api/sellers/tax-balance');
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

### 200 — Tax balance updated (success)

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [Get financial checkpoints](https://docs-staging.payme.io/keep/partners-api/getcheckpoints): GET /partner/api/statistic/checkpoints — Get financial checkpoints

# Get financial checkpoints

- Sandbox: `GET https://sandbox.payme.io/api/partner/api/statistic/checkpoints`
- Production: `GET https://live.payme.io/api/partner/api/statistic/checkpoints`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve financial checkpoints for a seller

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `socialId` | query | string | yes | Seller social/business ID |
| `reportingYear` | query | integer | yes | Reporting year |
| `reportingMonths` | query | string | no | Reporting months array |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/partner/api/statistic/checkpoints?socialId=<socialId>&reportingYear=<reportingYear>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/statistic/checkpoints?socialId=<socialId>&reportingYear=<reportingYear>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/partner/api/statistic/checkpoints?socialId=<socialId>&reportingYear=<reportingYear>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/partner/api/statistic/checkpoints?socialId=<socialId>&reportingYear=<reportingYear>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Successful response (success)

| Field | Type | Description |
| --- | --- | --- |
| `checkpoints` | array |  |

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```

- [Get tax predictions](https://docs-staging.payme.io/keep/partners-api/gettaxpredictions): GET /partner/api/statistic/tax-predictions — Get tax predictions

# Get tax predictions

- Sandbox: `GET https://sandbox.payme.io/api/partner/api/statistic/tax-predictions`
- Production: `GET https://live.payme.io/api/partner/api/statistic/tax-predictions`

## Credentials

- Header `Authorization: Bearer <token>`

Retrieve tax predictions for a seller

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `socialId` | query | string | yes | Seller social/business ID |
| `reportingYear` | query | integer | yes | Reporting year |
| `reportingMonths` | query | string | no | Reporting months array |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/partner/api/statistic/tax-predictions?socialId=<socialId>&reportingYear=<reportingYear>' \
  -H 'Authorization: Bearer <YOUR_TOKEN>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/partner/api/statistic/tax-predictions?socialId=<socialId>&reportingYear=<reportingYear>", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <YOUR_TOKEN>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/partner/api/statistic/tax-predictions?socialId=<socialId>&reportingYear=<reportingYear>",
    headers={
        "Authorization": "Bearer <YOUR_TOKEN>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/partner/api/statistic/tax-predictions?socialId=<socialId>&reportingYear=<reportingYear>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <YOUR_TOKEN>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — Successful response (success)

| Field | Type | Description |
| --- | --- | --- |
| `predictions` | array |  |
| `predictions[].reportingYear` | string |  |
| `predictions[].reportingMonth` | string |  |
| `predictions[].totalIncomesWithoutVat` | number |  |
| `predictions[].totalIncomesOriginTaxDeduction` | number |  |
| `predictions[].totalDeductibleExpenses` | number |  |
| `predictions[].yearlyPredictedProfit` | number |  |
| `predictions[].predictedTaxAmount` | number |  |
| `predictions[].paychecksPredictedSalary` | number |  |
| `predictions[].paychecksPredictedTax` | number |  |
| `predictions[].refundPointsValue` | number |  |
| `predictions[].predictedTaxRateADV` | number |  |

### 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 |
| --- | --- | --- |
| `error` | string |  |
| `error_description` | string |  |

```json
{
  "error": "unauthorized_client",
  "error_description": "Client authentication failed"
}
```