# Issuing the receipt

> How eKasa issues a receipt: a paper receipt, a PDF file or an e-mail, offline mode and additional texts on the receipt.

Source: https://ekasa.ninedigit.sk/en/docs/receipt-registration/printing

eKasa issues every receipt: it prints it, saves it as a PDF or sends it by e-mail. You choose the way when registering; otherwise the receipt is issued the default way from the settings (printed by default).

When registering a receipt, the parent application can specify how the receipt will be issued.

You may give the customer an electronic receipt (PDF or e-mail) instead of a printed one only if the customer agrees and asks for it before the receipt is printed ([§ 8(1) of Act No. 384/2025 Coll.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-8.odsek-1)). There is always only one original of the receipt: either printed or electronic. The customer must get the electronic receipt right after paying, just like a printed one: sending or making it available counts as handing over the receipt, which must happen immediately.

Choosing the way of issuing is not allowed for every receipt type, as the table below shows.

| Receipt type | Receipt type identifier | Way of issuing can be chosen |
|-----|-----|-----|
| Cash register receipt | `CashRegister` | Yes |
| Paragon | `Paragon` | No |
| Invoice | `Invoice` | Yes |
| Paragon for an invoice payment | `InvoiceParagon` | No |
| Invalid receipt | `Invalid` | No |
| Cash deposit and withdrawal | `Deposit`, `Withdraw` | No |

For receipt types marked “No”, the receipt is always issued the default way from the application settings.

You set the way of issuing with the `print.printerName` property.

Three options are supported:

- [Paper receipt](#pos) (`pos`): The cash register printer prints the receipt.
- [PDF file](#pdf) (`pdf`): eKasa creates the PDF file, your software delivers it to the customer.
- [E-mail](#email) (`email`): eKasa creates the PDF file and e-mails it to the customer itself.

Both electronic options create the same PDF file. They differ in who delivers it to the customer:

| | `email` | `pdf` |
|-----|-----|-----|
| Who delivers the receipt | eKasa e-mails it to the address from the request (`options.To`) | your software: it downloads the PDF file through the API ([Getting the PDF file](#getting-the-pdf-file)) and delivers it itself |
| What you need | an SMTP server in the eKasa settings | handling the PDF file in your software |
| When to use it | the customer wants the receipt by e-mail and it is fine for eKasa to send it | you deliver the receipt your own way, for example to a customer portal, an app or by your own e-mail |

If the `print` object is not specified, the receipt is issued the default way from the application settings, a paper receipt (`pos`) by default.

If the eKasa system does not respond at the moment, the receipt is issued on paper even if you asked for a PDF or
e-mail. See [When the eKasa system does not respond](#offline).

**HTTP API:**

The body of a receipt registration request, sent by the parent application to the HTTP API, contains two properties side by side at the top level:

1. `request`: information about the receipt itself
1. `print`: information about how the receipt is issued

The `print` property lets you specify how the receipt is issued with these properties:

- `printerName`: sets the way the receipt is issued.
- `options`: sets required and optional switches that affect issuing the receipt (depending on the way of issuing, see below).

Example:

```jsonc
{
  "request": {
    "data": { /* … receipt data */ }
  },
  "print": {
    "printerName": "pos",
    "options": { /* … issuing options */ }
  }
}
```

**.NET library:**

Library function `client.RegisterReceiptAsync()`

1. `RegisterCashRegisterReceiptRequest request`: information about the receipt itself
1. `RegisterReceiptPrintContext printContext`: information about how the receipt is issued

The `printContext` parameter lets you specify how the receipt is issued with these properties:

- `printerName`: sets the way the receipt is issued.
- `options`: sets required and optional switches that affect issuing the receipt (depending on the way of issuing, see below).

## <span id="pos" class="anchor"></span><span id="pos---paper-receipt" class="anchor"></span><code class="heading-tag">pos</code> Paper receipt

The default way of issuing a receipt.

To issue the receipt on paper, set the `printerName` field to `pos`.

The `options` object can contain these values:

| Name | Required | Description |
|-----|-----|-----|
| `OpenDrawer` | No | Sets whether the cash drawer opens (value `true`) or not (value `false`) for this particular receipt. This lets the parent application decide for which receipt types or payment methods the cash drawer should open. If set, it takes priority over the setting in the application configuration. |
| `PrintLogo` | No | Sets whether the graphic logo is printed (value `true`) or not (value `false`) for this receipt. If set, it takes priority over the setting in the application configuration. |
| `LogoMemoryAddress` | No | Sets which logo is printed for this receipt. If set, it takes priority over the setting in the application configuration. |

**HTTP API:**

```json
{
  "print": {
    "printerName": "pos",
    "options": {
      "OpenDrawer": false,
      "PrintLogo": true,
      "LogoMemoryAddress": 1
    }
  },
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 1.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 1.99,
          "vatRate": 23.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 1.99
        }
      ]
    }
  }
}
```

**.NET library:**

```csharp
// we can override default client configuration with these optional fields:
var printOptions = new PosPrintingOptions()
{
    // this will override the "configuration.Printers.Pos.Drawer.Enabled"
    // for this specific receipt.
    OpenDrawer = false,
    // this will override the "configuration.Printers.Pos.Logo.Enabled"
    // for this specific receipt.
    PrintLogo = true,
    // this will override the "configuration.Printers.Pos.Logo.MemoryAddress"
    // for this specific receipt.
    LogoMemoryAddress = 1
};

// prepare print context object from printer name and printing options
var printContext = RegisterReceiptPrintContext.CreatePos(printOptions);

// wrap receipt to request
var receiptRequest = new RegisterCashRegisterReceiptRequest(receipt);

// and register receipt
var result = await client.RegisterReceiptAsync(receiptRequest, printContext, cancellationToken);
```

## <span id="pdf" class="anchor"></span><span id="pdf---electronic-receipt-as-a-pdf-file" class="anchor"></span><code class="heading-tag">pdf</code> Electronic receipt as a PDF file

With `printerName` `pdf` eKasa does not print the receipt but creates a PDF file from it. Your software delivers it
to the customer, for example by e-mail, in an app or on the web:

1. Register the receipt with `"printerName": "pdf"`.
2. [Download the PDF file through the API](#getting-the-pdf-file).
3. Deliver it to the customer right away, for example by e-mail or a link in your app. The customer must get it
   immediately after paying, not later in a batch. If you need it for longer, store it on your side.

The `options` object can contain:

| Name | Required | Description |
|-----|-----|-----|
| `OpenDrawer` | no | Opens (`true`) or does not open (`false`) the cash drawer for this receipt. Takes priority over the application setting. |

**HTTP API:**

```json
{
  "print": {
    "printerName": "pdf"
  },
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 1.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 1.99,
          "vatRate": 23.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 1.99
        }
      ]
    }
  }
}
```

**.NET library:**

```csharp
// the only option for the pdf printer is OpenDrawer; without options
// the application configuration is used.
var printContext = RegisterReceiptPrintContext.CreatePdf();

// wrap receipt to request
var receiptRequest = new RegisterCashRegisterReceiptRequest(receipt);

// and finally, register the receipt
var result = await client.RegisterReceiptAsync(receiptRequest, printContext, cancellationToken);

// PDF file is created now, by default in the "receipts" folder
// of the application working directory.
```

### Getting the PDF file

You download the PDF file by the receipt identifier, the same way as when [looking up a receipt](https://ekasa.ninedigit.sk/en/docs/receipt-lookup). Always
include the cash register code (`cashRegisterCode`). The receipt is found even when it is missing from the
[index table](https://ekasa.ninedigit.sk/en/docs/glossary#tabulka-indexov).

**HTTP API:**

The request `GET /api/v1/printers/pdf/receipt` returns the PDF file. If the receipt or its file does not exist, the
response has HTTP status 404. All parameters are described in the [HTTP API reference](https://ekasa.ninedigit.sk/en/docs/rest-api/reference#tag/printers/GET/api/v1/printers/pdf/receipt).

| Identify the receipt by | Parameters |
|---|---|
| external identifier | `externalId` |
| internal identifier | `id` |
| receipt number | `year`, `month` and `receiptNumber` |

```bash
curl -o receipt.pdf "http://localhost:3010/api/v1/printers/pdf/receipt?cashRegisterCode=88812345678900001&externalId=order-1024"
```

**.NET library:**

The `client.GetPdfReceiptStreamAsync` method returns the PDF file as a `Stream`. You identify the receipt with a
`SingleReceiptRegistrationFilter`: by external identifier, internal identifier or receipt number.

```csharp
SingleReceiptRegistrationFilter filter = new SingleReceiptRegistrationFilter(
    cashRegisterCode: "88812345678900001",
    receiptNumberId: new ReceiptNumberId(year: 2026, month: 1, number: 1));

Stream stream = await client.GetPdfReceiptStreamAsync(filter, cancellationToken);
```

### Where eKasa stores PDF files

PDF files are created on the disk of the device where eKasa runs, in the folder from the
`printers.pdf.outputDirectory` setting. The default value `receipts` is relative to the application working
directory:

| System | Folder |
|---|---|
| Windows | `C:\ProgramData\NineDigit\Portos.eKasa\receipts\` |
| macOS and Linux | `/etc/NineDigit/Portos.eKasa/receipts/` |

The file is named `{cash register code}_{year and month}_{receipt number}.pdf`, for example
`88812345678900001_202601_000123.pdf`.

eKasa deletes PDF files automatically after 31 days; after that you cannot download them through the API. If you
need the receipt for longer, download it right after registration and store it in your software.

## <span id="email" class="anchor"></span><span id="email---electronic-receipt-as-an-e-mail" class="anchor"></span><code class="heading-tag">email</code> Electronic receipt as an e-mail

To issue the receipt as an e-mail, set the `printerName` field to `email`.

The `options` object can contain these values:

| Name | Required | Description |
|-----|-----|-----|
| `To` | Yes | E-mail address of the recipient (the e-mail the receipt is sent to). The receipt is sent **to one address only**: a carbon copy (`CC`) or a blind carbon copy (`BCC`) is not possible, because the law knows only one original of a cash register receipt. If you also need to keep the receipt (for example in an archive), use [`pdf`](#pdf): you download the PDF file and both deliver it to the customer and keep it yourself. |
| `Subject` | No | Sets the e-mail subject used for this particular receipt. If set, it takes priority over the setting in the application configuration (`printers.email.subject`). |
| `Body` | No | Sets the e-mail body used for this particular receipt. If set, it takes priority over the setting in the application configuration (`printers.email.body`). |
| `RecipientDisplayName` | No | Sets the display name of the e-mail recipient. |
| `OpenDrawer` | No | Sets whether the cash drawer opens (value `true`) or not (value `false`) for this particular receipt. This lets the parent application decide for which receipt types or payment methods the cash drawer should open. If set, it takes priority over the setting in the application configuration. |

**HTTP API:**

```json
{
  "print": {
    "printerName": "email",
    "options": {
      "To": "john.doe@example.com",
      "Subject": "Váš e-doklad",
      "Body": "Ďakujeme za nákup.",
      "RecipientDisplayName": "John Doe"
    }
  },
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        {
          "type": "positive",
          "name": "Coca Cola",
          "quantity": {
            "amount": 1.00,
            "unit": "ks"
          },
          "unitPrice": 1.99,
          "price": 1.99,
          "vatRate": 23.00
        }
      ],
      "payments": [
        {
          "name": "Hotovosť",
          "amount": 1.99
        }
      ]
    }
  }
}
```

**.NET library:**

```csharp
// required parameter - recipient's e-mail address
var printOptions = new EmailPrintingOptions("john.brown@example.com")
{
    // optional parameter. this will override
    // the "configuration.Printers.Email.Subject"
    // for this specific receipt.
    Subject = "Your receipt, mr. Brown!",
    // optional parameter. This will override
    // the "configuration.Printers.Email.Body"
    //  for this specific receipt.
    Body = "Thank you for your purchase.",
    // optional parameter - recipient's display name
    RecipientDisplayName = "John Brown"
};

// prepare print context object from printing options
var printContext = RegisterReceiptPrintContext.CreateEmail(printOptions);

// wrap receipt to request
var receiptRequest = new RegisterCashRegisterReceiptRequest(receipt);

// and register receipt
var result = await client.RegisterReceiptAsync(receiptRequest, printContext, cancellationToken);
```

### System behaviour after a failed e-mail

If the receipt is recorded and written to the storage but sending the e-mail fails, **the receipt registration
succeeds**: eKasa returns the usual registration result and reports no error. It writes the sending failure to the log
and keeps the receipt PDF in the same folder as for an electronic receipt in PDF form (see
[Getting the PDF file](#getting-the-pdf-file)). After a successful send, the PDF file is deleted.

eKasa does not retry the e-mail: the same receipt must not be issued more than once. If the e-mail was not sent, give
the receipt to the customer another way, for example print a [receipt copy](https://ekasa.ninedigit.sk/en/docs/receipt-lookup#printing-a-receipt-copy).

You find the cause in the service logs (in the web interface, menu **Systém → Údržba** (System → Maintenance)). The
most common causes are:

- **connection to the server**: check the SMTP server address and port; if the server does not support SSL, choose
  **Použiť TLS, ak je k dispozícii** (Use TLS if available) in the **Typ pripojenia** (Connection type) field,
- **sign-in**: check the e-mail account credentials,
- **recipient address**: the server rejected the address (`RecipientNotAccepted`).

## <span id="offline" class="anchor"></span>When the eKasa system does not respond

eKasa registers most receipts online: it sends the data message to the eKasa system and issues the receipt with its
response. If the eKasa system does not respond within the timeout (10 seconds by default) or there is no connection,
eKasa registers the receipt **in offline mode**. Selling continues, only the way the receipt is issued changes:

```mermaid
flowchart TD
    A{printerName} -->|pos| P1[Paper receipt]
    A -->|pdf or email| B{eKasa system<br/>responded?}
    B -->|yes, online| E[PDF file or e-mail]
    B -->|no, offline| P2[Paper receipt<br/>OFF-LINE DOKLAD]
```

- **The receipt is on paper.** The Financial Administration guidelines require a receipt registered offline to be
  on paper. eKasa therefore issues it the default way from the settings (a paper receipt `pos` by default), even if
  you asked for `pdf` or `email`. No PDF file or e-mail is created, not even later when the data message is sent.
- **The receipt is valid.** Instead of the unique identifier (UID) it carries the business signature code (PKP) and
  a QR code with the business verification code (OKP).
- **Do not repeat anything.** eKasa sends the data message to the eKasa system by itself. Do not register the
  receipt again.

Your software recognises an offline receipt by the result `isSuccessful: null` (in .NET `IsSuccessful == null`), see
[Registration result](https://ekasa.ninedigit.sk/en/docs/receipt-registration/result). You can tell the cashier that the receipt was printed
and the customer should get the paper receipt, because no e-mail was sent.

If printing the paper receipt fails (for example, it is out of paper), the error
[`-502: PrintReceiptError`](https://ekasa.ninedigit.sk/en/docs/rest-api/error-codes#-502-printreceiptererror) is returned. The receipt is still
registered and queued, so do not send it for registration again. Once the problem is fixed, you can print a
[copy of the receipt](https://ekasa.ninedigit.sk/en/docs/receipt-lookup) for the customer. If the customer insists on the original,
[cancel](https://ekasa.ninedigit.sk/en/docs/receipt-registration/corrections#receipt-cancellation) the original receipt and register a new one.

The whole offline flow is described in [How eKasa works](https://ekasa.ninedigit.sk/en/docs/how-it-works#when-there-is-no-internet).

## Additional texts on the receipt

The receipt has extra properties for adding additional texts to it.

| Name | Description | Note |
|----|----|----|
| `headerText` | Text printed right after the identification data | When tokens are used, the `pageBreak` token is not applied |
| `footerText` | Text printed at the end of the receipt, after the QR code and the receipt identifier | |

Both properties support `token`s for formatting and for printing QR codes and barcodes. More in the article [Tokens and text formatting](https://ekasa.ninedigit.sk/en/docs/token-syntax).

Example:

```json
{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "invoiceNumber": "FA-2026-0001",
      "amount": 189.90,
      "headerText": "Nine Digit, s.r.o.\nweb: www.ninedigit.sk",
      "footerText": "Ďakujeme za úhradu faktúry.\nPotvrdenie o platbe nájdete aj\nv klientskej zóne na www.ninedigit.sk."
    }
  }
}
```

This is what the issued receipt looks like. The header is right below the identification data of the seller and the
receipt, the footer is at the end of the receipt:

[Image: Invoice payment receipt with the header text (Nine Digit, s.r.o., web) below the identification data and the thank-you note in the footer at the end of the receipt highlighted]

## Where next

- [Registration result](https://ekasa.ninedigit.sk/en/docs/receipt-registration/result): Receipt number, identifier and VAT summary.
- [Tokens and formatting](https://ekasa.ninedigit.sk/en/docs/token-syntax): Bold text, alignment, QR codes and barcodes in text.
- [Non-fiscal receipt](https://ekasa.ninedigit.sk/en/docs/nonfiscal-receipt): Printing your own text outside the records.
