Create Payper Invoice API

Index

Create Payper Invoice API – Complete Reference

POST https://gateway21.pelecard.biz/services/CreatePayperInvoice

Content-Type: application/json

⚠️ CRITICAL – VAT Calculation

Pelecard does NOT calculate VAT!

All amounts must be sent already WITH VAT included. The system will not add VAT to your amounts.

Example: If product costs ₪100 + 18% VAT, send price_per_unit: "11800" (not “10000”)

Quick Start

Basic Request Template

{
  "terminalNumber": "YOUR_TERMINAL",
  "user": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "trxRecordId": "",
  "Uid": "",
  "PayperParameters": {
    "typeDocument": "invoice",
    "DataPayper": {
      "document_lang": "en",
      "document_no_vat": "false",
      "customer_mail": "customer@example.com",
      "customer_name": "John Doe",
      "send_by_mail": "false",
      "invoice_lines": [
        {
          "description": "Product Name",
          "quantity": "1",
          "price_per_unit": "10000",
          "include_vat": "false"
        }
      ]
    }
  }
}

Success Response

{
  "StatusCode": "000",
  "ErrorMessage": "operation success",
  "PayperData": {
    "InvoiceStatus": "Success",
    "InvoiceLink": "https://app.payper.co.il/public/invoice_show/...",
    "InvoiceNumber": "1234"
  }
}

Supported Document Types

Type typeDocument Value When to Use
Invoice "invoice" Regular invoice without payment
Proforma "proforma" Quote or estimate
Bid "bid" Commercial offer or tender
Receipt "receipt" Simple payment receipt
Invoice-Receipt "invoice-receipt" or "Invoice-Receipt" Invoice with payment confirmation*
Credit "credit" Refund or credit note

* Requires Payper activation – Contact Pelecard support: 03-6579500

Request Parameters

Authentication (Required)

Parameter Type Required Description
terminalNumber string Yes Your Pelecard terminal number
user string Yes API username
password string Yes API password
trxRecordId string Yes Transaction record ID. Use "" for invoices without card payment, or transaction ID for card payments
Uid string Yes Unique transaction ID. Use "" for invoices without card payment, or transaction UID for card payments

💡 When to use trxRecordId and Uid

Empty strings "":

  • Creating invoice/proforma/bid (no payment yet)
  • Invoice-receipt for cash/check payment
  • Any document not linked to a card transaction

Filled with transaction IDs:

  • Invoice-receipt created after card payment
  • Linking invoice to existing card transaction

Example: If customer pays ₪100 by card, you get trxRecordId from payment API. Use those IDs when creating invoice-receipt for that specific payment.

PayperParameters Object

Parameter Type Required Description
typeDocument string Yes Document type (see table above)
DataPayper object Yes Customer and invoice data

DataPayper Object – Required Fields

Parameter Type Required Description Example
document_lang string Yes Document language "hb" (Hebrew) or "en" (English)
document_no_vat string Yes Document without VAT "true" / "false"
customer_mail string Conditional* Customer email address "customer@example.com"
customer_unique_id string Conditional* Customer ID or business number "123456789"
customer_name string Yes Customer full name "John Doe"
invoice_lines array Yes Invoice items (see below) [{...}]
receipt_lines array Conditional** Payment receipt info (see below) [{...}]

* Either customer_mail OR customer_unique_id is required (can be changed in Payper settings)

** Required only for invoice-receipt type

DataPayper Object – Optional Fields

Parameter Type Description Example
customer_mobile string Customer cell phone number "0544444444"
customer_business_phone string Customer business phone "036579500"
customer_address string Customer address "123 Main St, Tel Aviv"
document_subject string Document subject/title "Monthly Invoice"
document_payment_due_date string Payment deadline (DD-MM-YYYY) "31-12-2025"
document_remarks string Notes or comments "Thank you"
reference_document_id string Source document system ID "12345"
send_by_mail string Send email to customer "true" / "false"
document_rounded string Round document price "true" / "false"
Discount_with_vat string Discount amount (agorot). WARNING: If used, receipt amount must be adjusted! "500"
extra_recipients string Additional emails (comma-separated) "a@test.com,b@test.com"
developer_email string Email for API errors "dev@company.com"
income_id string Revenue type ID (Payper setting) "335"

invoice_lines Array

Parameter Type Required Description Example
description string Yes Item description "Product A"
quantity string Yes Item quantity "1", "2"
price_per_unit string Yes Price in agorot (smallest unit) "10000" = ₪100
include_vat string Yes CRITICAL: Add 18% VAT to price. Always required! "true" / "false"
No_vat string No Item without VAT (requires include_vat: false) "true" / "false"
catalog_id string No Product catalog ID "1111"

🚨 CRITICAL: include_vat is REQUIRED!

Every item in invoice_lines MUST have “include_vat” field!

Without this field, you will get error 146: “קיים חוסר התאמה בין סכום התקבולים לסכום התשלומים”

Always include:

"invoice_lines": [
  {
    "description": "Product",
    "quantity": "1",
    "price_per_unit": "10000",
    "include_vat": "true"  // ← REQUIRED!
  }
]

receipt_lines Array (for invoice-receipt)

Parameter Type Required Description Example
payment_type string Yes Payment method "Cash", "Cc" (Credit Card), "Check", "BankTransfer", "Other"
date string Yes Payment date (DD-MM-YYYY) "15-11-2025"
amount number Yes Must equal invoice total (with VAT) 11800 or -11800 for refund
cc_num string No Last 4 digits of credit card "1234"

⚠️ Receipt Amount Requirements

  • Payment: Amount must be POSITIVE and equal invoice total (including VAT)
  • Refund: Amount must be NEGATIVE (e.g., -11800)
  • Multiple payments: Sum of all amounts must equal invoice total

🚨 CRITICAL: Discount_with_vat and Receipt Amount

If you use Discount_with_vat, you MUST adjust the receipt amount!

Formula:

receipt amount = (Σ invoice_lines) - Discount_with_vat

Example:

// Invoice lines total: 10000
// Discount: 500
// Receipt amount must be: 10000 - 500 = 9500

"Discount_with_vat": "500",
"receipt_lines": [{
  "amount": 9500  // ← NOT 10000!
}]

Common Error: If receipt amount = 10000 but discount = 500, you’ll get error 146!

Solution: Either remove Discount_with_vat OR adjust receipt amount to match.

Important Notes

⚠️ Critical Requirements

  1. Pelecard does NOT calculate VAT – Send amounts already WITH VAT
  2. All prices in agorot (smallest currency unit): "10000" = ₪100.00
  3. trxRecordId and Uid are mandatory – Use empty strings "" for invoices without card payment (cash, future payment), or fill with transaction IDs for card payments
  4. Boolean values – Use strings: "true" or "false"
  5. Date format – Use DD-MM-YYYY (e.g., "15-11-2025")
  6. Receipt amount for refunds – Must be NEGATIVE

VAT Calculation Examples

Important: The include_vat parameter tells the system how to DISPLAY the amount, but you must still send the correct total.

When include_vat: “true”

  • Send the base price in price_per_unit
  • System adds 18% VAT for display
  • Example: "10000" displays as ₪118.00 (₪100 + 18% VAT)

When include_vat: “false”

  • Send the final price in price_per_unit
  • No VAT added for display
  • Example: "10000" displays as ₪100.00

For invoice-receipt amount calculation:

  • If include_vat: “true” → amount = price_per_unit × quantity × 1.18
  • If include_vat: “false” → amount = price_per_unit × quantity

invoice-receipt Amount Calculation

Without VAT:

"invoice_lines": [{"price_per_unit": "10000", "include_vat": "false"}]
// Total: 10000 agorot

"receipt_lines": [{"amount": 10000}]  // Must match!

With VAT:

"invoice_lines": [{"price_per_unit": "10000", "include_vat": "true"}]
// Total: 10000 × 1.18 = 11800 agorot

"receipt_lines": [{"amount": 11800}]  // Must be 11800!

Refund Process

📝 How to Process Refunds

After creating an Invoice-Receipt, to process a complete refund you need to create 2 documents:

Step 1: Create Credit Invoice (Positive Amount)

{
  "typeDocument": "credit",
  "DataPayper": {
    "reference_document_id": "12345",  // Original document ID
    "invoice_lines": [{
      "description": "Refund",
      "quantity": "1",
      "price_per_unit": "10000",  // POSITIVE
      "include_vat": "false"
    }]
  }
}

Step 2: Create Receipt (Negative Amount)

{
  "typeDocument": "receipt",
  "DataPayper": {
    "reference_document_id": "12345",  // Original document ID
    "invoice_lines": [{
      "description": "Refund",
      "quantity": "1",
      "price_per_unit": "10000",
      "include_vat": "false"
    }],
    "receipt_lines": [{
      "payment_type": "Cc",
      "date": "15-11-2025",
      "amount": -10000  // NEGATIVE!
    }]
  }
}

CRITICAL: Receipt amount must be NEGATIVE for refunds!

Error Codes – Complete Reference

Success Response

Code Description
200 ✅ Success – Request completed successfully

Authentication & Authorization

Code Description Solution
110 Unauthorized credentials Check API key/token in Payper settings
111 Unknown IP address Whitelist IP in Payper settings (no spaces)
112 Unauthorized External Shop credentials External shop feature not enabled – contact support
113 Unauthorized Interface credentials Interface feature not enabled – contact support
120 Link required Missing required message content
401 Unauthorized Authentication verification failed
403 Forbidden Request validation failed

Customer Management

Code Description Solution
130 Customer details missing Provide customer_mail or customer_unique_id
133 New customer name required Add customer_name for new customer
134 Customer not found Check customer_unique_id exists
135 Price for customer not found No purchase history for this customer/item
155 Customer identifier missing Customer identifier parameters required
156 Item SKU missing Product SKU is required

Document & Invoice Management

Code Description Solution
126 Reference invoice not found Check reference_document_id value
127 Reference invoice misfit Referenced document type incorrect for this operation
140 Invalid document type Use: invoice, proforma, bid, receipt, invoice-receipt, credit
142 Invoice lines missing Add invoice_lines array
143 Incomplete line items Check description and price_per_unit
144 Receipt lines missing Add receipt_lines for invoice-receipt
145 Invalid receipt data Check payment_type, amount, date format
146 Invoice creation error 1. Receipt amount must equal invoice total (with VAT)
2. Check Payper document numbering settings
147 Duplicate document Identical document already created recently
167 Invoice already issued for order Order ID already processed

Proforma Management

Code Description Solution
650 Document ID missing Document identifier required
660 Proforma not found No proforma found with provided ID
661 Multiple proformas found Data inconsistency – contact support
662 Proforma can’t be canceled Cannot cancel already-paid proforma

Catalog & Inventory

Code Description Solution
301 Catalog item not found Product not found in catalog – check catalog_id

File Upload

Code Description Solution
909 File name not valid Include file extension (e.g., filename.pdf)
910 File name missing File name is required
911 File type not valid Accepted types: pdf, png, jpg, jpeg
912 File link or base64 missing Provide file URL or base64 content
915 Receiving file error Error processing uploaded file

Date & Time Formats

Code Description Solution
8010 Wrong DateTime format Check date-time format
8011 Wrong Date format Use DD-MM-YYYY format

Common Error Messages (Hebrew)

Error Message Translation Solution
קיים חוסר התאמה בין סכום התקבולים לסכום התשלומים Receipt amount doesn’t match invoice total Check: receipt amount must equal invoice total (with VAT)
שים לב, תחילה יש להשלים הגדרות ראשוניות להפקת מסמכים Document setup incomplete Check ‘Document Numbering’ in Payper settings
payper invoice does not allowed Payper not activated Call Pelecard: 03-6579500

Complete Example

Invoice-Receipt with All Fields

{
  "terminalNumber": "YOUR_TERMINAL",
  "user": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "trxRecordId": "",
  "Uid": "",
  "PayperParameters": {
    "typeDocument": "Invoice-Receipt",
    "DataPayper": {
      "document_lang": "en",
      "document_no_vat": "false",
      "customer_unique_id": "123456789",
      "customer_mail": "customer@example.com",
      "customer_name": "ABC Company Ltd",
      "customer_mobile": "0544444444",
      "customer_business_phone": "036579500",
      "customer_address": "123 Main Street, Tel Aviv",
      "document_subject": "Monthly Invoice",
      "document_payment_due_date": "31-12-2025",
      "document_remarks": "Thank you for your business",
      "send_by_mail": "true",
      "document_rounded": "false",
      "extra_recipients": "manager@company.com,accounting@company.com",
      "developer_email": "dev@company.com",
      "income_id": "335",
      "invoice_lines": [
        {
          "description": "Professional Services",
          "quantity": "3",
          "price_per_unit": "10000",
          "include_vat": "true",
          "No_vat": "false",
          "catalog_id": "1111"
        }
      ],
      "receipt_lines": [
        {
          "payment_type": "Cc",
          "date": "15-11-2025",
          "cc_num": "1234",
          "amount": 35400
        }
      ]
    }
  }
}

Note: Discount_with_vat removed from this example to avoid amount mismatch issues. If you need to use discounts, see the “Discount_with_vat” section above for proper amount calculation.

Postman Collection

Download our comprehensive Postman collection with 13 examples:

  • 3 Invoice examples (simple, with VAT, full with all fields)
  • 1 Proforma example
  • 1 Bid example
  • 1 Receipt example
  • 3 Invoice-Receipt examples (cash, credit card, multiple payments)
  • 1 Invoice-Receipt with Discount example (correct amount calculation) ⭐ NEW
  • 2 Refund examples (credit invoice + negative receipt)

Setup:

  1. Import collection into Postman
  2. Set variables: terminalNumber, user, password
  3. Optionally set trxRecordId1, Uid1 for testing
  4. Start testing with “Invoice – Simple”

⚠️ CRITICAL: Every invoice_lines item MUST have “include_vat” field!

Testing Checklist

Before going to production:

  • ✅ Test with typeDocument: "invoice" first
  • ✅ Verify trxRecordId and Uid included (use empty strings "" for invoices without card payment)
  • ✅ Confirm amounts are WITH VAT if required
  • ✅ Test VAT calculations (10000 × 1.18 = 11800)
  • ✅ For invoice-receipt: verify amount matches total
  • ✅ Test email with send_by_mail: "true"
  • ✅ Test refund process (credit + negative receipt)
  • ✅ Verify invoice links work
No data was found