# Basic Invoicing Hyp Pay comes with a built-in integration with **Hyp Invoice** (formerly EZcount), a popular Israeli invoicing service. This allows you to automatically generate tax invoices or receipts whenever a transaction is successfully processed. Invoicing is enabled on your terminal by default. When active, Hyp Pay can handle document generation for you, making sure your customers get their proof of purchase without you having to work hard for it. ## How automatic invoicing works When the invoicing module is active, Hyp Pay is designed to issue an invoice **automatically** for every successful transaction, including refunds, cancellations, and payouts. You don't need to make a separate API call to generate a document — instead, you just pass the relevant invoicing parameters along with your payment request. The data you send in your payment request directly affects what appears on the generated document. If you don't provide specific invoicing details, Hyp Pay will use default values from your terminal configuration. ## Choosing the default document type In your Hyp Pay account, you can choose what kind of document you want to generate. To do this, log in to your account and click **הגדרת מסמך ברירת מחדל** (**Setting a default document**) under **הגדרות** (**Settings**). In the **סוג מסמך ברירת מחדל** (**Default document type**) dropdown, ‎ **קבלה**‎ **/** **חשבונית מס‎** (**Tax invoice receipt**) is selected by default, but you can alternatively select **קבלה** (**Receipt**). If you're a non-profit company, you can also set donation receipt as the default document type. After making changes, remember to click **עדכון הגדרות ברירת מחדל** (**Update default settings**). ## Controlling invoice delivery By default, Hyp Pay won't send the invoice to the customer automatically unless you explicitly tell it to. You can control this using the `SendHesh` parameter: * `SendHesh`: Set this to `True` if you want the system to email the invoice to the customer. For this to work, you'll also need to provide the customer's email address in the `email` parameter. * `sendHeshSMS`: If you have an SMS package with Hyp, setting this to `True` will send a link to the invoice via SMS to the phone number provided in the `cell` parameter. ## Customizing invoice details You can fine-tune the information shown on the invoice using several optional parameters: * `heshDesc`: A general description of the purchase that appears in the *Details* cell on the invoice. If you aren't sending a detailed list of items, this is where you describe the service or product. * `EZ.lang`: The language of the invoice and the accompanying email. Use `he` for Hebrew (default) or `en` for English. * `EZ.comment`: Additional text that will be added after the body of the invoice document. * `EZ.description`: Text that will be inserted as the subheader of the invoice. * `EZ.email_text`: Additional text in the body of an email. * `EZ.vat`: Allows you to override the default VAT rate. For example, use `0` for VAT-exempt transactions. * `EZ.cc_emails`: You can provide a list of up to 10 additional email addresses to receive a copy of the invoice. * `EZ.customer_crn`: The customer's company number or ID (BN number). Israeli law requires this for documents worth more than 5,000 ILS. ## Adding line items to your invoice If you want your invoice to show a detailed list of products or services instead of just one total amount, you can use the `Pritim` and `heshDesc` parameters together. First, set `Pritim` to `True` to let the system know you're sending a list of items. Then, you format your items in the `heshDesc` parameter using a specific structure. Each item must be enclosed in square brackets `[]`, and the details within those brackets are separated by a tilde `~`. The format for each item is: `[item_code~description~quantity~price_including_vat]` If you don't have a specific bookkeeping code for an item, just use `0`. Here's an example of how to format the `heshDesc` string for a purchase of one shirt at 80 ILS and two pairs of socks at 20 ILS each: `[0~Blue Shirt~1~80][0~Cotton Socks~2~20]` When you use the `Pritim=True` flag, Hyp Pay multiplies the quantity by the price for each item and sums them up. This total must exactly match the `Amount` parameter you sent for the transaction. If there's a mismatch, the transaction will fail with [error code 400](/pay/reference/response-status-codes.md). Make sure there are no extra characters or digits between the sets of brackets. Just like with all parameters passed in your payment page request, remember to URL-encode the value of `heshDesc`. ## Generating links to invoices If you need to provide your customers with a way to download their invoices directly from your own application or website, you can generate a secure, temporary link to the invoice document. Generating a link is a two-step process. First, you make a server-to-server request to get a secure signature for the specific invoice. Then, you use that signature to build the final URL that the customer can click. ### Step 1: Request a signature To ensure that invoice links cannot be tampered with, you must first request a signature from the Hyp Pay API. This call must be made from your backend to keep your API credentials secure. Here's an example API request to get a signature for an invoice: {% code overflow="wrap" %} ```http https://pay.hyp.co.il/p/?Masof=0010210290&action=APISign&KEY=your-api-key&What=SIGN&PassP=your-api-password&TransId=55373520&type=EZCOUNT&ACTION=PrintHesh ``` {% endcode %} When making this request, you'll need to provide these key parameters: * `action`: Set this to `APISign`. * `ACTION`: The operation to be signed. For invoices, this must be `PrintHesh`. * `Masof`, `KEY`, and `PassP`: Your terminal identification details. * `What`: Set this to `SIGN`. * `TransId`: The unique ID of the transaction to generate an invoice link for. * `asm`: The unique ID of the invoice document to link to. This is not required if `TransId` is provided. * `type`: Set this to `EZCOUNT`. A successful response returns a URL-encoded string containing the signature: {% code overflow="wrap" %} ``` Masof=0010345518&TransId=408615223&action=PrintHesh&type=EZCOUNT&signature=76942f55ffe7e2d7ba9d2501792a394cbce4e7d00de3da0d71f372ae919db9cd ``` {% endcode %} ### Step 2: Build the final link Once you have the signature from Step 1, you can create the final link by appending the entire successful response string to the Hyp Pay base URL: `https://pay.hyp.co.il/p/?`. Using the example response above, the final link would be: {% code overflow="wrap" %} ```http https://pay.hyp.co.il/p/?Masof=0010345518&TransId=408615223&action=PrintHesh&type=EZCOUNT&signature=76942f55ffe7e2d7ba9d2501792a394cbce4e7d00de3da0d71f372ae919db9cd ``` {% endcode %} When a customer clicks this link, their browser will immediately download the PDF version of the invoice. ## Creating invoices for offline transactions Sometimes you need to issue an invoice for payments that didn't happen through a credit card on your website — for example, **when a customer pays with cash or a check**. You can use the Hyp Pay API to record these "offline" transactions and generate the appropriate tax documents. This process uses the `action=soft` command. No actual money is moved by Hyp Pay; the system simply records the payment and triggers the invoicing module. Here's an example API request to record a cash payment of 200 ILS and generate an invoice: {% code overflow="wrap" %} ```http https://pay.hyp.co.il/p/?action=soft&Masof=0010345518&PassP=your-api-password&Amount=200&TransType=Cash&SendHesh=True&Info=Offline+cash+payment&email=jennyp@example.co.il&ClientName=Jenny&ClientLName=Parkington&UserId=890108558 ``` {% endcode %} To record an offline transaction, you'll typically send these parameters: * `action`: Set this to `soft`. * `Masof` and `PassP`: Your terminal number and API password. * `Amount`: The amount received (e.g., `200` or `10.50`). * `TransType`: The type of payment. Use `Cash` or `Check`. * `SendHesh`: Set to `True` if you want to email the invoice to the customer. * `email`: Your customer's email address. * `ClientLName` - Your customer's last name. * `UserId`: Your customer's Israeli ID. If unknown or not applicable, use `000000000`. * `Info`: A description of the transaction for your records. A successful response contains `CCode=0`, which confirms that the transaction was recorded and the invoice was generated: ``` Id=416194874&CCode=0&Amount=200&ACode=&Fild1=&Fild2=&Fild3=&Hesh=EZ ``` ## Examples of invoices When a transaction goes through successfully, Hyp Pay will email the customer with a link to download the PDF file of the invoice or receipt. If you've chosen to send the invoice via SMS, they'll also get a link on their phone. This is an example of a tax invoice receipt in Hebrew with one line item, the standard tax rate and one payment method: ![Tax invoice receipt in Hebrew](/files/P8mOyhV16X4lGj8R7lwf) Here's a regular receipt in English with two line items, a discounted VAT, and two purchase methods (a credit card and a gift card): ![Receipt in English with two payment methods](/files/b6p18mSbIAhCT4hp0dph) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.hyp.co.il/pay/invoicing/basic-invoicing.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.