Create a document

Credentials

⚠️ This API is deprecated and is no longer recommended for use. For questions, contact partners@payme.io.

Overview

Creates an invoice, receipt or other tax document for the seller through PayMe's invoicing service. The seller's invoicing service must be active; otherwise every documents call returns error 703 (HTTP 403).

Documents are created asynchronously: the response returns doc_id and doc_url at once, but the document may not be ready yet. While the document job is still running (its status is waiting, active, delayed, paused or stuck), Get a document returns error 1005 with HTTP 400 and the status in status_additional_info, for example status:waiting. Wait a few seconds and call it again.

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 it, then call again.

PayMe passes amounts, totals and vat_rate to the invoicing service as you send them. Don't send card numbers or CVVs: a document needs no card data.

Document types

The types you can create are listed on Document types.

Documents issued automatically

With the invoicing service active on the account, a paid sale issues a document and a refund (including a refund of a subscription charge) automatically issues a credit document. A refund never un-issues the original document; canceling a document takes a separate counter-document. To skip the automatic document for one API sale, send "services": [{"name": "invoice", "settings": {"active": false}}] on generate-sale.

Authentication

Name the seller with seller_payme_id in the body or the PayMe-Merchant-Key header. A partner may instead send payme_client_key (body or PayMe-Partner-Key header) with its own seller_id. With no credential at all, the call returns error 1 with status_additional_info payme_client_key.

Errors

HTTP Code When
400 20 Validation failed. status_additional_info lists the messages per field.
400 1 A partner key was sent, but no seller. status_additional_info is seller_payme_id.
400 20 The seller doesn't belong to this partner. status_additional_info is Merchant-Seller inconsistency.
403 703 The invoicing service isn't active for this seller.
500 1 No credential was sent at all. status_additional_info is payme_client_key.
500 251 The seller key is unknown.
500 163 The seller isn't active.
500 200 The partner key is unknown.
500 201 The partner isn't active.
500 1001 The invoicing service returned an error. status_additional_info carries its code and details.
503 1001 The invoicing service didn't answer in time.
500 1004 The invoicing service didn't create the document.

Parameters

Name In Type Required Description
PayMe-Merchant-Key header string no The seller's MPL, instead of seller_payme_id in the body.

Request body

Content type: application/json

Field Type Required Description
seller_payme_id string yes The seller's MPL. You can send it in the PayMe-Merchant-Key header instead.
payme_client_key string no Partners only: your partner key, in the body or the PayMe-Partner-Key header.
seller_id string no Partners only: your own reference for the seller, instead of seller_payme_id. Needs payme_client_key.
doc_type integer yes Document type: 100, 200, 300, 305, 320, 330, 400, 405 or 600. See Document types.
buyer_name string yes Buyer name printed on the document.
buyer_address string no Buyer address printed on the document.
buyer_social_id string no Buyer national ID or company number, printed as the buyer's tax ID. Default: credit_card.buyer_social_id.
currency string no ISO 4217 currency code of the document.
language string no Document language: he (default) or en.
doc_date string no Document date, for example 2026-11-09.
due_date string no Payment due date.
pay_date string no Date the payment was made.
doc_title string no Title printed at the top of the document.
doc_comments string no Comments printed on the document.
exchange_rate number no Exchange rate used on the document.
vat_rate number no VAT rate applied to the document.
discount number no Discount applied to the document.
total_excluding_vat number no Total before VAT.
total_sum_after_discount number no Total after the discount.
total_sum_including_vat number no Total including VAT.
total_vat number no Total VAT.
total_paid number no Total paid on this document.
total_paid_including_vat number no Total paid, including VAT.
items array yes Document lines. At least one.
items[].description string yes Line description, at least 3 characters.
items[].unit_price number no Unit price before VAT. Send unit_price or unit_price_with_vat.
items[].unit_price_with_vat number no Unit price including VAT.
items[].quantity integer no Quantity.
items[].vat_exempt boolean no true if the line is exempt from VAT.
items[].currency string no ISO 4217 currency code of the line.
items[].exchange_rate number no Exchange rate of the line's currency.
cash object no Cash payment received. Send it only for cash that was actually paid.
cash.sum number yes Amount paid in cash.
cheques array no Cheques received.
cheques[].sum number yes Cheque amount.
cheques[].date string yes Cheque date.
cheques[].bank number no Bank code. See Banks in Israel.
cheques[].branch number no Branch number.
cheques[].account string no Account number, digits only.
cheques[].number string no Cheque number, digits only.
bank_transfer object no Bank transfer received. Send it only for a transfer that was actually made.
bank_transfer.sum number yes Amount transferred.
bank_transfer.date string no Date the transfer was received.
bank_transfer.account string no Account number, digits only.
paypal object no PayPal payment received.
paypal.sum number yes Amount paid with PayPal.
paypal.date string yes Payment date.
paypal.transaction_id string yes PayPal transaction ID.
paypal.buyer_name string yes Payer name.
credit_card object no Card payment received. Don't send the card number or CVV.
credit_card.sum number yes Amount paid by card.
credit_card.date string no Payment date.
credit_card.installments integer no Number of installments.
credit_card.first_payment number no Amount of the first installment.
credit_card.type string no Card brand, for example Visa.
credit_card.expiry string no Card expiry, exactly 4 characters MMYY. Must not be in the past.
credit_card.buyer_name string no Card holder's name.
credit_card.buyer_social_id string no Card holder's national ID, digits only. Also printed as the buyer's tax ID when buyer_social_id isn't sent.
credit_card.auth_number string no Authorization number of the card payment.

Request example

{
  "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",
    "expiry": "1230",
    "buyer_name": "Israel Israeli",
    "auth_number": "0123456"
  }
}

Code samples

curl

curl -X POST 'https://sandbox.payme.io/api/documents' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  --data-raw '{
  "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",
    "expiry": "1230",
    "buyer_name": "Israel Israeli",
    "auth_number": "0123456"
  }
}'

Node.js

const response = await fetch("https://sandbox.payme.io/api/documents", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
  body: JSON.stringify({
    "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",
      "expiry": "1230",
      "buyer_name": "Israel Israeli",
      "auth_number": "0123456"
    }
  }),
});

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

Python

import requests

response = requests.post(
    "https://sandbox.payme.io/api/documents",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    json={
        "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",
            "expiry": "1230",
            "buyer_name": "Israel Israeli",
            "auth_number": "0123456",
        },
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "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",
    "expiry": "1230",
    "buyer_name": "Israel Israeli",
    "auth_number": "0123456"
  }
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/documents');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

echo $response;

Responses

200 — The document job was created. (success)

Field Type Description
status_code integer 0 on success.
doc_id string The document's job ID. Use it with Get a document.
doc_num string The document number, once the invoicing service has assigned one.
doc_status string Status of the document job, when the invoicing service returns one.
doc_url string Link to the document.
doc_type integer Document type. See Document types.
buyer_name string Buyer name on the document.
buyer_address string Buyer address on the document, if sent.
doc_date string Document date.
due_date string Payment due date, if sent.
pay_date string Payment date, if sent.
currency string ISO 4217 currency code of the document.
language string Document language.
doc_title string Title printed at the top of the document.
doc_comments string Comments printed on the document.
exchange_rate number Exchange rate used on the document.
vat_rate number VAT rate applied to the document.
discount number Discount applied to the document.
total_excluding_vat number Total before VAT.
total_sum_after_discount number Total after the discount.
total_sum_including_vat number Total including VAT.
total_vat number Total VAT.
total_paid number Total paid on this document.
total_paid_including_vat number Total paid, including VAT.
items array Document lines.
items[].description string Line description.
items[].quantity integer Quantity.
items[].unit_price number Unit price before VAT.
items[].unit_price_with_vat number Unit price including VAT.
items[].vat_exempt boolean true if the line is exempt from VAT.
items[].currency string ISO 4217 currency code of the line.
items[].exchange_rate number Exchange rate of the line's currency.
cash object Cash payment recorded on the document.
cash.sum number Amount paid in cash.
cheques array Cheques recorded on the document.
cheques[].sum number Cheque amount.
cheques[].date string Cheque date.
cheques[].bank number Bank code.
cheques[].branch number Branch number.
cheques[].account string Account number.
cheques[].number string Cheque number.
bank_transfer object Bank transfer recorded on the document.
bank_transfer.sum number Amount transferred.
bank_transfer.date string Transfer date.
bank_transfer.account string Account number.
paypal object PayPal payment recorded on the document.
paypal.sum number Amount paid with PayPal.
paypal.date string Payment date.
paypal.transaction_id string PayPal transaction ID.
paypal.buyer_name string Payer name.
credit_card object Card payment recorded on the document. It holds no card number or CVV.
credit_card.sum number Amount paid by card.
credit_card.installments integer Number of installments.
credit_card.first_payment number Amount of the first installment.
credit_card.type string Card brand.
credit_card.expiry string Card expiry, MMYY.
credit_card.buyer_name string Card holder's name.
credit_card.buyer_social_id string Card holder's national ID.
credit_card.auth_number string Authorization number of the card payment.
authority_redirect_url string Returned instead of the other fields when the seller must first approve the connection to the Israel Tax Authority. No document was created. 
{
  "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",
  "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",
    "expiry": "1230",
    "buyer_name": "Israel Israeli",
    "auth_number": "0123456"
  },
  "doc_url": "https://invoice-staging.paymeservice.com/documents/fa397fce-aee6-4c6d-ae9c-273ae1e3a317"
}

400 — Validation failed (20), or a partner key came without a seller (1). (error)

Field Type Description
status_code integer 1 on failure.
status_error_details string What went wrong.
status_additional_info object For a validation error, the messages per field, each an array of strings. Otherwise the field concerned, as a string.
status_error_code integer PayMe error code: 20 for a validation error.
session string PayMe session ID. Quote it when you contact support. 
{
  "status_code": 1,
  "status_error_details": "The given data was invalid.",
  "status_additional_info": {
    "doc_type": [
      "The doc type field is required."
    ],
    "items": [
      "The items field is required."
    ],
    "buyer_name": [
      "The buyer name field is required."
    ]
  },
  "status_error_code": 20,
  "session": "FhT3aXe7"
}

403 — The invoicing service isn't active for this seller (703). (error)

Field Type Description
status_code integer 1 on failure.
status_error_details string What went wrong, in the language you asked for (Hebrew by default).
status_additional_info string The field or value concerned. Can be null.
status_error_code integer PayMe error code. See the error table above and Errors.
session string PayMe session ID. Quote it when you contact support. 
{
  "status_code": 1,
  "status_error_details": "Action is not permitted",
  "status_additional_info": "Invoicing Service was not properly activated. Operation not permitted",
  "status_error_code": 703,
  "session": "FhT3aXe7"
}

500 — Credentials or the invoicing service failed. See the error table. (error)

Field Type Description
status_code integer 1 on failure.
status_error_details string What went wrong, in the language you asked for (Hebrew by default).
status_additional_info string The field or value concerned. Can be null.
status_error_code integer PayMe error code. See the error table above and Errors.
session string PayMe session ID. Quote it when you contact support. 
{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "payme_client_key",
  "status_error_code": 1,
  "session": "FhT3aXe7"
}