Issue invoices and receipts for your sales

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
• Get a document
• List documents
• Document types
• Callback types reference
• Refund a sale
• List sales
• Create a sale (hosted payment page)
• Get API access and go live: from sandbox to production

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 (partners@payme.io) before building on it.

Choose how to issue documents

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.

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 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: 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:

{
  "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 (partners@payme.io) 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:

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, 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.

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.

{
  "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, passing the doc_id:

curl https://sandbox.payme.io/api/documents/fa397fce-aee6-4c6d-ae9c-273ae1e3a317 \
  -H 'PayMe-Merchant-Key: MPLDEMO-MPLDEMO-MPLDEMO-1234567'

A not-ready answer looks like this:

{
  "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 returns the seller's documents a page at a time:

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

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 explains, check documents on a small live sale that you refund straight away.

Related

• Create a document, Get a document, List documents
• Document types
• Callback types
• Refund a sale