# How eKasa works

> Fiscalisation in Slovakia in a nutshell: the eKasa system of the Financial Administration, the cash register client program, the CHDÚ storage and what your software handles.

Source: https://ekasa.ninedigit.sk/en/docs/how-it-works

Before you start writing code, it pays to understand who takes part in issuing a receipt and who is responsible
for what. This article explains it without technical details; those are in the following articles.

## Fiscalisation in Slovakia in brief

A business must record every cash and card sale in an **online cash register** (ORP, “online registračná
pokladnica”). At the moment of sale, it sends each receipt to the **eKasa system** of the Financial Administration
of the Slovak Republic. The eKasa system accepts the receipt and assigns it a **unique identifier** (UID), which
is printed on the receipt. The rules are set by
[Act No. 384/2025 Coll. on recording sales](https://www.slov-lex.sk/ezbierky/pravne-predpisy/SK/ZZ/2025/384/) (in Slovak).

Only software certified by the Financial Administration, the **cash register client program** (PPEKK,
“pokladničný program eKasa klient”), may:

- communicate with the eKasa system,
- write to the **protected data storage** (CHDÚ, “chránené dátové úložisko”), where data can be neither deleted nor changed,
- issue and print the cash register receipt.

Your point-of-sale software therefore does not issue or print the receipt itself, nor send it to the eKasa system.
The certified program does it.

## Library or service: choose your technology

We release the certified Nine Digit eKasa program in two forms:

- as a **.NET library** (NuGet package) that you add directly to your .NET application,
- as an **HTTP API service** that wraps this library and runs on **Windows, macOS, Linux and Android**.

Thanks to the API service you are not tied to .NET: you talk to eKasa over HTTP and JSON from any programming
language and environment, for example PHP, Java, JavaScript or Python. Both forms do the same, and this article
applies to both.

## Who takes part in a receipt

```mermaid
sequenceDiagram
    autonumber
    participant S as Your software
    participant K as eKasa
    participant C as CHDÚ storage
    participant F as eKasa system
    participant D as Receipt
    S->>K: sale data
    K->>C: write the receipt
    K->>F: send the receipt
    F-->>K: unique identifier
    K->>C: write the response
    K->>D: print, PDF or e-mail
    K-->>S: registration result
```

Your software talks only to eKasa: it sends the sale data (1) and gets the registration result (7). It never
connects directly to the storage, the printer or the eKasa system; eKasa does everything in between. It writes
every step to the storage: the receipt being sent (2), the eKasa system's response (5) and, when printing through
the storage, the printed output too.

| Who | What it does |
|---|---|
| **Your software** (the *parent application* in this documentation) | Sells: puts together items, prices, VAT rates and payments, and sends the receipt to eKasa. Shows the result to the cashier. |
| **Nine Digit eKasa** (PPEKK) | Validates the receipt, calculates VAT, writes it to the storage, sends it to the eKasa system and issues it on paper or electronically. |
| **CHDÚ storage** | Keeps the business's data (identification and authentication data) and a record of every data message sent. |
| **eKasa system** (Financial Administration) | Accepts the receipt and assigns it a unique identifier. |

Your software therefore does not have to deal with communication with the Financial Administration, signing,
writing to the storage or print layout. It only sends eKasa the sale data and processes the response.

## What happens when you send a receipt

This is a simplified request: two pieces of goods with a discount, paid by card.

**HTTP API:**

```http
POST http://localhost:3010/api/v1/requests/receipts/cash_register
Content-Type: application/json
```

```json
{
  "request": {
    "data": {
      "cashRegisterCode": "88812345678900001",
      "items": [
        { "type": "positive", "name": "Coca Cola", "quantity": { "amount": 2, "unit": "ks" }, "unitPrice": 1.99, "price": 3.98, "vatRate": 23 },
        { "type": "discount", "name": "Loyalty discount", "quantity": { "amount": 1 }, "unitPrice": -1.00, "price": -1.00, "vatRate": 23 }
      ],
      "payments": [ { "name": "Card", "amount": 2.98 } ]
    }
  }
}
```

**.NET library:**

```csharp
var items = new ReceiptItems
{
    new ReceiptItem(ReceiptItemType.Positive, "Coca Cola", 1.99m, new Quantity(2, "ks"), 23m),
    new ReceiptItem(ReceiptItemType.Discount, "Vernostná zľava", -1.00m, 1, 23m)
};

var receipt = new CashRegisterReceipt("88812345678900001", items)
{
    Payments = new ReceiptPayments { new ReceiptPayment("Platobná karta", 2.98m) }
};

RegisterReceiptResult result = await client.RegisterReceiptAsync(
    new RegisterCashRegisterReceiptRequest(receipt),
    RegisterReceiptPrintContext.CreatePos(),
    cancellationToken);
```

eKasa first validates the data (required fields, totals, Financial Administration rules) and calculates the
turnover for each VAT rate and the business verification code. Then it follows the steps in the diagram above: it
writes the receipt to the storage, sends it to the eKasa system, writes the response, issues the receipt and returns
the result to your software.

For an electronic receipt, eKasa can just prepare the PDF and leave its delivery to the customer, for example by
e-mail or in an app, to your software. Issuing and printing the receipt always stays with eKasa.

In the result, three fields matter most:

**HTTP API:**

```json
{
  "request": { "data": { "receiptNumber": 2, "okp": "04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0" } },
  "response": { "data": { "id": "O-7DBCDA8A56EE426DBCDA8A56EE426D1A" } },
  "isSuccessful": true
}
```

**.NET library:**

```csharp
// unique identifier, e.g. O-7DBCDA8A56EE426DBCDA8A56EE426D1A
// (null until the receipt is registered online)
EKasaReceiptId? id = result.Response?.Data.Id;

// business verification code, e.g. 04eacca4-6ff07dea-c2c85513-28181bb6-f46edcb0
OKP okp = result.Request.Data.OKP;

// true, null or false
bool? isSuccessful = result.IsSuccessful;
```

- `response.data.id` (in .NET `Response.Data.Id`) is the **unique identifier** of the receipt assigned by the eKasa system,
- `request.data.okp` (in .NET `Request.Data.OKP`) is the **business verification code** (OKP, “overovací kód podnikateľa”), calculated by eKasa before sending,
- `isSuccessful` tells you how the registration went (see below).

## When there is no internet

If the eKasa system is not available, sales do not stop. eKasa registers the receipt **in offline mode**:

- it always prints the receipt on paper, even if you asked for PDF or e-mail,
- the receipt carries the business verification code (OKP) instead of the unique identifier,
- it stores the data message in the **queue of unsent messages** and sends it on its own as soon as the connection is back.

```mermaid
sequenceDiagram
    participant S as Your software
    participant K as eKasa
    participant F as eKasa system
    S->>K: receipt
    K-xF: sending fails (no internet)
    Note over K: prints the receipt with OKP,<br/>stores the data message in the queue
    K-->>S: isSuccessful: null
    Note over K,F: connection restored
    K->>F: data message from the queue
    F-->>K: unique identifier
```

The business must make sure that every data message reaches the eKasa system **within 96 hours** of the first
attempt to send it ([§ 3(1) of Act No. 384/2025](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-3.odsek-1), in Slovak). That is why it is worth monitoring the queue, as described in [System status](https://ekasa.ninedigit.sk/en/docs/status).

The `isSuccessful` field can therefore have three values:

| `isSuccessful` | What happened | Receipt identifier |
|---|---|---|
| `true` | the receipt is registered online | `response.data.id` |
| `null` | the receipt is registered offline and waits in the queue | `request.data.okp` |
| `false` | the eKasa system rejected the receipt | details in the `error` field |

## Receipt lifecycle

The whole path of a receipt from the request to the issued receipt, with the result your software gets:

```mermaid
stateDiagram-v2
    state "Data check" as check
    state "Written to the CHDÚ" as stored
    state "Sent to the eKasa system" as sent
    state "Registered online" as online
    state "In the queue (offline)" as queued
    state "Rejected" as rejected
    state "Issued" as issued
    [*] --> check: your software sends the receipt
    check --> [*]: validation error, nothing is stored
    check --> stored
    stored --> sent
    sent --> online: isSuccessful true
    sent --> queued: no response, isSuccessful null
    sent --> rejected: error, isSuccessful false
    online --> issued: paper, PDF or e-mail
    queued --> issued: paper with OKP
    queued --> online: the queue sends the message within 96 h
    rejected --> [*]
    issued --> [*]
```

eKasa rejects invalid data before writing to the storage; your software can fix it and send it again. A receipt
written to the CHDÚ cannot be taken back: if it was issued by mistake, [cancel it](https://ekasa.ninedigit.sk/en/docs/receipt-registration/corrections).

## Integration and production environment

The Financial Administration runs the eKasa system in two environments. The **integration** environment is for
development and testing with a fictitious business; sales in it do not count. The **production** environment is
the live one for real businesses. At the start of development you will work in the integration environment, often
without a physical storage. How to do that is described in [Environment setup](https://ekasa.ninedigit.sk/en/docs/environment-setup).

## Where next

- [Storage and hardware](https://ekasa.ninedigit.sk/en/docs/storage-and-hardware): Which CHDÚ storage to choose and how to set up a computer, tablet or terminal.
- [Environment setup](https://ekasa.ninedigit.sk/en/docs/environment-setup): Integration environment, test storage and installing eKasa.
- [Receipt registration](https://ekasa.ninedigit.sk/en/docs/receipt-registration): All receipt types, items, payments and the registration result.

Abbreviations such as CHDÚ, OKP or PKP are explained in the [Glossary](https://ekasa.ninedigit.sk/en/docs/glossary).
