Hyp Website

Issuing Invoices

Issuing invoices requires invoicing to be enabled in your terminal.

If the invoice module was enabled during Hyp onboarding, you can start working with the invoicing API immediately. Otherwise, follow the steps in Enabling Invoicing in the Terminal before you begin.

To generate an invoice for a regular debit transaction, send a standard Hyp API request and, in the int_in parameter, include an XML payload for the addCgInvoice command. The XML payload should look like this:

<ashrait>
    <request>
        <version>2000</version>
        <language>ENG</language>
        <command>addCgInvoice</command>
        <addCgInvoice>
            <invoiceAtranId>119284861</invoiceAtranId>
            <terminalNumber>{terminalNumber}</terminalNumber>
            <invoice>
                <invoiceCreationMethod>wait</invoiceCreationMethod>
                <invoiceSubject>Invoice for your purchase</invoiceSubject>
                <invoiceItemCode>12345</invoiceItemCode>
                <invoiceItemDescription>Item description</invoiceItemDescription>
                <invoiceItemQuantity>1</invoiceItemQuantity>
                <invoiceItemPrice>12500</invoiceItemPrice>
                <companyInfo>Invoice recipient</companyInfo>
                <mailTo>[email protected]</mailTo>
                <isItemPriceWithTax>1</isItemPriceWithTax>
                <ccDate>2025-08-07</ccDate>
            </invoice>
        </addCgInvoice>
    </request>
</ashrait>

The language element under request determines the language of the invoice, which can be either Hebrew (HEB) or English (ENG).

The command element should be set to addCgInvoice, and the addCgInvoice element must contain the following child elements:

  • terminalNumber: a unique number assigned to you as a merchant during registration.

  • invoiceAtranId: the tranId of the debit transaction you want to generate an invoice for. If you don't have the tranId, perform an inquire transaction to retrieve it.

  • invoice: the wrapper element for the invoice parameters:

    • invoiceCreationMethod: one of two invoice generation methods:

      • post initiates invoice generation and returns an immediate response confirming that generation has started. To retrieve the resulting invoice, you must later make a separate inquiry call to fetch the invoice URL.

      • wait ensures that the response includes the resulting invoice URL. This may take longer but avoids the need for a separate inquiry call.

    • invoiceSubject: the subject of the invoice, up to 255 alphanumeric characters.

    • invoiceItemCode: the product identifier (מק"ט) based on the merchant's item cataloging system. Numeric, up to 500 characters.

    • invoiceItemDescription: item description, up to 500 alphanumeric characters.

    • invoiceItemQuantity: quantity of the item. Can be an integer or a decimal with two fractional places (e.g., 123.45).

    • invoiceItemPrice: single item price.

    • companyInfo: the customer's full details, such as a personal name or company name. Up to 255 characters.

    • mailTo: the email address to send the invoice to.

    • isItemPriceWithTax: indicates whether invoiceItemPrice includes (1) or excludes (0) VAT. For implications of this setting, see VAT calculation below.

    • ccDate: the date (YYYY-MM-DD) to appear on the invoice. Must be on or after the transaction date.

The invoice element may also include the following optional parameters:

  • Parameters that override your invoice account details.

  • clientAddress: the customer's address, up to 60 characters.

  • clientOsekNum: the customer's tax registration number (ק סוע רפסמ), exactly 9 characters.

  • DocNotMaam: indicates whether tax fields are included (1, default) or excluded (0) in the invoice.

  • DocRemark: free-form description to include in the invoice, up to 255 characters. Supported only when invoiceType is set to receipt.

  • invoiceComments: comments (up to 255 characters) not shown on the invoice but stored for internal records.

  • invoiceDate: the invoice record date (YYYY-MM-DD) in EZcount. Defaults to the current date.

  • invoiceDiscount: discount amount in currency subunits (e.g., agorot or cents). Mutually exclusive with invoiceDiscountRate. For details, see Discount management.

  • invoiceDiscountRate: discount rate as a percentage with two fractional places (e.g., 12.50). Mutually exclusive with invoiceDiscount. See Discount management.

  • invoiceItemMaam: indicates whether to show an item with (1) or without (0) VAT.

  • invoiceSignature: signature to append to the invoice.

  • invoiceTaxRate: VAT rate for invoice calculations, specified as a percentage with two fractional places (e.g., 17.25).

  • sendMail: enables (1) or disables (0) sending the generated invoice by email to the customer. Defaults to 1.

  • ua_uuid: an EZcount identifier defining the design layout to use when generating the invoice.

Adding multiple items to an invoice

The example above shows an invoice for a single item. However, invoices often include multiple items.

Each addCgInvoice command can only contain one set of the five item-related parameters:

  • invoiceItemCode

  • invoiceItemDescription

  • invoiceItemQuantity

  • invoiceItemPrice

  • invoiceItemMaam (optional)

To list multiple items, include each value in the corresponding element and separate them with the pipe symbol (|). Make sure each element contains the same number of items, listed in the same order.

For example, the following request is for an invoice with three items:

Validation and calculation rules for invoice parameters

Most documents generated by Hyp using the addCgInvoice command are fiscal documents that cannot be freely modified once issued. For this reason, Hyp enforces strict validation of key parameters to ensure accurate accounting and an exact match between the invoice and its underlying transaction.

Amount total validation

To generate a valid invoice, the Hyp API verifies that the sum of all item totals matches the total amount paid in the transaction for which the invoice is being issued. If this check fails, the invoice is not created and EZcount returns error code 131.

This validation applies whether the invoice contains one item or multiple items — the check always uses the sum of all (price × quantity) values.

The validation formula is:

For an invoice with a single item:

For an invoice with multiple items:

VAT calculation

The isItemPriceWithTax element specifies whether the item prices in your invoice request already include VAT. This setting affects how invoiceItemPrice and invoiceDiscount are processed.

If isItemPriceWithTax is set to 1 (prices include VAT):

  1. EZcount will subtract the VAT portion from each invoiceItemPrice and display item prices excluding VAT in the invoice. It will also calculate and display:

    1. The total before VAT.

    2. VAT from all items.

    3. The total after VAT.

  2. The same VAT adjustment is applied to invoiceDiscount. For example, if invoiceDiscount is 1000 (₪10) and VAT is 18%, the effective discount is calculated as 1000 / 1.18 = 847.46 (≈₪8.48).

Discount management

You can set discounts in your invoice request using either invoiceDiscount or invoiceDiscountRate, but not both in the same request.

When invoiceDiscount is used, the total is calculated as follows:

When invoiceDiscountRate is used, the total is calculated like this:

For example, if the original transaction total is ₪99 (9900 in agorot) and you applied a 10% discount, you can represent this in the invoice request in either of the following ways:

  1. Using invoiceDiscount:

  2. Using invoiceDiscountRate:

Response structure

Here's a success response to the invoice request for three items shown in Adding multiple items to an invoice above:

This example shows a response to a request with invoiceCreationMethod set to wait, which is why it includes the invoiceDocUrl element containing a ready-to-use link to the generated invoice.

If invoiceCreationMethod is set to post, the response does not include the invoice link because the document may not be ready yet. In that case, you must send an invoice inquiry using the invoiceAtranId value from the response to retrieve the invoice URL.

Some elements under invoice in the response are identical to those in the request, while others differ. The notable response-specific elements are:

  • invoiceAtranId: the new transaction ID (tranId) for the invoice.

  • invoiceResponseCode: EZcount status code (100 indicates success).

  • invoiceResponseName: EZcount status message.

  • invoiceDocNumber: invoice number generated according to the numbering settings you configured during EZcount registration.

  • invoiceDocUrl: URL to access the generated invoice.

  • invoiceCreationDate: invoice creation time in Unix timestamp (epoch) format.

When the Hyp API returns a success response, EZcount also emails the generated invoice to the customer, unless sending is disabled in the request.

The invoice email looks like this:

EZcount invoice email

The customer can download the invoice PDF by clicking the button in the email. Below is an example of a PDF tax invoice receipt for a purchase of three items:

EZcount invoice PDF
PreviousEnabling Invoicing in the TerminalNextOverriding Invoice Account Details in the Request

Last updated

Was this helpful?