# Issue invoices and receipts for your sales Building with an AI agent? Start at https://docs.payme.io/agents.md ## Prerequisites - The seller's seller_payme_id (MPL) - Invoicing set up on the seller's account by PayMe, for automatic documents - For the Documents API: its own activation on the seller's account ## Related - [Create a document](/payments/invoices/post-create-invoice) - [Get a document](/payments/invoices/show-generated-document-by-id) - [List documents](/payments/invoices/get-documents) - [Document types](/payments/codes-statuses/document-types) - [Callback types reference](/payments/getting-started/callback-types) - [Refund a sale](/payments/post-sale-actions/post-refund-sale) - [List sales](/payments/query-apis/post-get-sales) - [Create a sale (hosted payment page)](/payments/hosted-payment-page/post-generate-sale) - [Get API access and go live: from sandbox to production](/payments/getting-started/go-live) PayMe can issue tax documents for a seller, such as invoices, receipts and credit documents, in two ways: automatically for each sale and refund, or one at a time through the Documents API. This guide explains both, and how to get each document once it is ready. **The Documents API is deprecated.** Contact PayMe Partners () before building on it. ## Choose how to issue documents | | Automatic documents | Documents API (deprecated) | |---|---|---| | What you get | A document for each paid sale, and a credit document for each refund | Any supported document type, with the lines and payments you send | | What you call | Nothing new: the sale and refund calls you already make | `POST /documents`, then `GET /documents/{doc_id}` | | Setup | Invoicing set up on the seller's account by PayMe | A separate activation. Until then, every call returns error `703` | Use automatic documents when each document matches a PayMe sale. The Documents API is for documents with no PayMe sale behind them, for example a payment the seller received in cash or by bank transfer. To have either set up for a seller, ask PayMe Partners with the seller's MPL; see [Enable payment methods and services for your sellers](/marketplaces-and-platforms/seller-onboarding/enable-services). ## Automatic documents for each sale When invoicing is set up on the seller's account: - **Paid sale.** When a sale is paid, or an authorization is captured, PayMe issues a document of the type set in the seller's invoicing settings, for example a receipt or an invoice receipt. A sale that only saves a card (`sale_type: token`) gets no document. - **Refund.** Each refund, full or partial, issues a credit document for the refunded amount. The original document stays as it is. - **Lines.** If the sale has `items`, the document lists them. Otherwise it has one line with the sale's `product_name` and amount. - **Language.** Documents are in Hebrew. If the seller's settings ask for English documents for foreign sales, a sale in a currency other than ILS, or one paid with a foreign card, gets an English document. ### Get the document PayMe creates the document in the background, just after the sale or refund. - The `sale-complete` callback carries `sale_invoice_url`. For a refund, the [`refund-sale`](/payments/post-sale-actions/post-refund-sale) response and the `refund` callback carry it for the credit document. - `sale_invoice_url` is a PayMe link that opens the document once it has been created. Right after the sale, it can still show a "not found" page. - The document number may not be known yet when the callback is sent, so `sale_invoice_number` can be `null`. Read the number later with [`get-sales`](/payments/query-apis/post-get-sales): `sale_invoices` lists each document of the sale with its `invoice_doc_number` and `invoice_url`. ### Skip the document for one sale Send `services` with the `invoice` service turned off on [`generate-sale`](/payments/hosted-payment-page/post-generate-sale): ```json { "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "sale_price": 1000, "currency": "ILS", "product_name": "Order 1234", "transaction_id": "order-1001", "sale_callback_url": "https://your-server.example.com/payme/callback", "services": [ { "name": "invoice", "settings": { "active": false } } ] } ``` ## Create documents with the Documents API **Deprecated.** The Documents API is no longer recommended for new integrations. Contact PayMe Partners () before building on it. ### Activate it for the seller The Documents API needs its own activation on the seller's account. Until it is active, every documents call fails with error `703` and `status_additional_info` "Invoicing Service was not properly activated. Operation not permitted". Automatic documents don't activate it. Ask PayMe Partners to activate it. ### Authenticate - `POST /documents`: send the seller's MPL as `seller_payme_id` in the body, or in the `PayMe-Merchant-Key` header. - `GET /documents` and `GET /documents/{doc_id}`: send the MPL in the `PayMe-Merchant-Key` header. A GET has no body, so without the header the call fails with error `1`. - Partners may add `payme_client_key` (or the `PayMe-Partner-Key` header). The seller must then belong to you, or the call fails with error `20`. ### Create a document Call [Create a document](/payments/invoices/post-create-invoice): ```bash curl -X POST https://sandbox.payme.io/api/documents \ -H 'Content-Type: application/json' \ -d '{ "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567", "doc_type": 400, "buyer_name": "Israel Israeli", "doc_date": "2026-11-09", "currency": "ILS", "language": "he", "doc_title": "Receipt for order 1001", "total_paid": 140, "items": [ { "description": "Monthly plan", "quantity": 1, "unit_price": 140, "vat_exempt": false, "currency": "ILS" } ], "cash": { "sum": 40 }, "credit_card": { "sum": 100, "installments": 1, "type": "Visa", "buyer_name": "Israel Israeli", "auth_number": "0123456" } }' ``` - **`doc_type`** is required. Use one of the 9 codes on [Document types](/payments/codes-statuses/document-types), for example `305` tax invoice, `320` invoice receipt, `330` credit invoice or `400` receipt. - **`buyer_name`** and **`items`** are required. Send at least one line, and give each line a `description` of at least 3 characters. - **Payments** (`cash`, `cheques`, `bank_transfer`, `paypal`, `credit_card`) are optional. Send only payments that were actually received; each one needs a `sum`. - **`language`** is `he` (the default) or `en`. - **Amounts.** PayMe passes amounts, totals and `vat_rate` to the invoicing service as you send them. Each field is described on [Create a document](/payments/invoices/post-create-invoice). A request that fails validation returns error `20` (HTTP 400), with the messages for each field in `status_additional_info`. The response returns the document's job ID in `doc_id`, its link in `doc_url`, and the fields you sent. Keep `doc_id`. ```json { "status_code": 0, "doc_id": "fa397fce-aee6-4c6d-ae9c-273ae1e3a317", "doc_type": 400, "buyer_name": "Israel Israeli", "doc_date": "2026-11-09", "currency": "ILS", "language": "he", "total_paid": 140, "doc_url": "https://invoicing.example.com/documents/fa397fce-aee6-4c6d-ae9c-273ae1e3a317" } ``` **Israel Tax Authority approval.** If the seller still has to approve the connection to the Israel Tax Authority, the response holds only `authority_redirect_url`, and no document is created. Send the seller to that URL to approve, then create the document again. ### Wait for the document to be ready Documents are created asynchronously: the create call returns before the document exists. Read it with [Get a document](/payments/invoices/show-generated-document-by-id), passing the `doc_id`: ```bash curl https://sandbox.payme.io/api/documents/fa397fce-aee6-4c6d-ae9c-273ae1e3a317 \ -H 'PayMe-Merchant-Key: MPLDEMO-MPLDEMO-MPLDEMO-1234567' ``` | Response | Meaning | What to do | |---|---|---| | HTTP 400, error `1005`, `status_additional_info` such as `status:waiting` or `status:active` | The document is still being created | Wait a few seconds and call again. | | HTTP 200 with the document, `doc_num`, `doc_status` and `doc_url` | The document is ready | Use `doc_url` and `doc_num`. | | Error `1003` | The document failed to generate | Check the data you sent, then create the document again. | | HTTP 200 with `status_code` `0` and no document fields | The invoicing service reported an unknown job status | Call again later. | A not-ready answer looks like this: ```json { "status_code": 1, "status_error_details": "Document you're requested not ready yet", "status_additional_info": "status:waiting", "status_error_code": 1005, "session": "FhT3aXe7" } ``` ### List documents [List documents](/payments/invoices/get-documents) returns the seller's documents a page at a time: ```bash curl 'https://sandbox.payme.io/api/documents?limit=5&field=createdAt&sort=desc' \ -H 'PayMe-Merchant-Key: MPLDEMO-MPLDEMO-MPLDEMO-1234567' ``` `page` picks the page, `limit` the page size, `field` and `sort` (`asc` or `desc`) the order, and `from` and `to` filter by date. Each item has the fields of a document, including `doc_id`, but not `doc_url`: call Get a document for the link. ### Errors | Code | HTTP | Meaning | |---|---|---| | `703` | 403, or 400 when the activation is incomplete | The Documents API isn't active for the seller. | | `20` | 400 | Validation failed, or the seller doesn't belong to your partner account. | | `1` | 400 or 500 | A credential is missing: no seller with a partner key (400), or no key at all (500). | | `251` | 500 | The seller key is unknown. | | `1004` | 500 | The invoicing service didn't create the document. | | `1005` | 400 | The document isn't ready yet. | | `1003` | 500 | The document failed to generate. | | `1001` | 500 or 503 | The invoicing service returned an error (500) or didn't answer in time (503). | The full tables are on each endpoint page. ## Test documents The invoicing service doesn't run in the sandbox. As [Get API access and go live](/payments/getting-started/go-live) explains, check documents on a small live sale that you refund straight away. ## Related - [Create a document](/payments/invoices/post-create-invoice), [Get a document](/payments/invoices/show-generated-document-by-id), [List documents](/payments/invoices/get-documents) - [Document types](/payments/codes-statuses/document-types) - [Callback types](/payments/getting-started/callback-types) - [Refund a sale](/payments/post-sale-actions/post-refund-sale)