# QR payments

> Paying by QR code through the Financial Administration's instant payment notifier: the flow, four steps in the HTTP API and .NET, payment states, failure notice and FAQ.

Available from version: Windows 8.0.1, macOS 8.0.1, Linux 9.0.2, Android 8.0.1, .NET library (PPEKK) 8.0.1

Source: https://ekasa.ninedigit.sk/en/docs/qr-payments

A QR payment is a cashless payment without a payment terminal. The customer scans a QR code in their banking app
and pays by instant transfer. The cash register learns about the payment from the **instant payment notifier** (NOP)
run by the Financial Administration. eKasa talks to it for you.

A QR payment is a **separate step before receipt registration**. No receipt data is sent with it. Once the payment
is confirmed, your software registers the receipt as with any other cashless payment.

## Payment flow

```mermaid
sequenceDiagram
    autonumber
    participant S as Your software
    participant K as eKasa
    participant Z as Customer
    participant F as Financial Administration (NOP)
    S->>K: create payment (amount)
    K->>F: request payment ID
    F-->>K: payment ID and payment link
    K-->>S: payment ID and link
    S->>Z: QR code on a display or paper
    Z->>F: payment in the banking app
    S->>K: payment status?
    K-->>S: paid
    S->>K: receipt registration
```

## Steps

- [Payment ID](#1-payment-id): Creating a payment with an amount. The result is a payment ID and a payment link.
- [QR code](#2-qr-code-for-the-customer): Showing the QR code on your software's display or through eKasa.
- [Payment status](#3-waiting-for-the-payment): Waiting for the payment confirmation and its result.
- [Failure notice](#4-payment-failure-notice): The receipt printed when the payment does not arrive in time.

All request and response fields with examples are in the [HTTP API reference](https://ekasa.ninedigit.sk/en/docs/rest-api/reference#tag/payments);
in the .NET library, in the `QrPayment` class and the `IQrPaymentService` service. Below is only what the reference
does not tell you.

### 1. Payment ID

Every QR payment has a unique ID assigned by the Financial Administration. You send the amount and the cash register
code, eKasa requests a payment ID and returns it together with the payment link for the QR code. Store the ID: you
can use it to get the payment status even if the process is interrupted.

**HTTP API:**

```http
POST {server_address}/api/v1/payments/qr
Content-Type: application/json

{
  "amount": 19.90,
  "cashRegisterCode": "88812345678900001",
  "comment": "textova poznamka",
  "recipientMessage": "eKasa QR platba"
}
```

| Result | What to do |
|---|---|
| `201 Created` | The payment ID is in `transactionId`, the payment link in `links`. |
| `500`, code [`-701`](https://ekasa.ninedigit.sk/en/docs/rest-api/error-codes#-701-qrpaymentinitializationerror) | The payment could not be created; repeat the request. |

**.NET library:**

```csharp
IQrPaymentService qrPaymentService = client.QrPaymentService;

var request = new QrPaymentRequest(
    cashRegisterCode: "88812345678900001",
    amount: 19.90m,
    comment: "textova poznamka",
    recipientMessage: "eKasa QR platba");

IQrPaymentSession session = await qrPaymentService
    .InitiatePaymentAsync(request, cancellationToken);

QrPaymentTransactionId transactionId = session.Payment.TransactionId;
```

| Result | What to do |
|---|---|
| `session.Payment` | the current payment, the ID is in `TransactionId`; create the payment link with `CreatePaymentLink(QrPaymentLinkScheme.PaymeVersion2Point0)` |
| `session.Completion` | a task that completes when the payment reaches a final state (step 3) |
| `QrPaymentInitializationException` | the payment could not be created; create it again |

Optional data:

- `comment`: a note for the payment; eKasa sends it to the instant payment notifier (NOP) when the payment ID is
  generated.
- `recipientMessage`: a message for the recipient in the payment link, shown on the bank statement. If it is missing,
  the value from the [settings](https://ekasa.ninedigit.sk/en/docs/qr-payments/environment-setup#message-for-the-recipient) is used.

### 2. QR code for the customer

The QR code contains a [Payme](https://www.payme.sk) payment link following the
[SBA standard](https://www.sbaonline.sk/projekt/standard-platobnej-linky/), found in the `links` property of the
payment creation response. The QR code can be shown by:

- **your software** on the cash register display or a customer display,
- **eKasa**, if your software cannot do it. It prints the QR code on the cash register printer as a paper slip, so
  QR payments need no extra hardware:

**HTTP API:**

```http
POST {server_address}/api/v1/payments/qr/{transactionId}/render
Content-Type: application/json

{
  "rendererName": "posPrinter"
}
```

The response `204 No Content` means the QR code is printed. If the payment does not exist, `404 Not Found` is
returned.

**.NET library:**

```csharp
await qrPaymentService.RenderPaymentAsync(
    transactionId, QrPaymentRendererName.PosPrinter, cancellationToken);
```

If the payment does not exist, the method throws `QrPaymentNotFoundException`.

eKasa has no other way of showing the QR code than the cash register printer (`posPrinter`) yet. You can print your
own paper output with a QR code as a [non-fiscal receipt](https://ekasa.ninedigit.sk/en/docs/nonfiscal-receipt) with a QR code token (see
[Token syntax](https://ekasa.ninedigit.sk/en/docs/token-syntax)).

### 3. Waiting for the payment

Your software asks eKasa for the payment status until the confirmation arrives or the waiting time runs out. You set
the waiting time in your software. The law does not specify it; from experience we recommend **90 seconds**. The
cashier should also be able to stop waiting.

**HTTP API:**

```http
GET {server_address}/api/v1/payments/qr/{transactionId}?await=true
```

With `await=true`, the response returns only after the payment reaches a final state; without it (default `false`)
it returns immediately with the current state. The state is in the `status` property. If the payment is not found,
`404 Not Found` is returned ([`-702`](https://ekasa.ninedigit.sk/en/docs/rest-api/error-codes#-702-qrpaymentnotfounderror)).

**.NET library:**

```csharp
// the current state at any time
QrPayment current = session.Payment;

// waiting for a final state: Paid, Overpaid or Expired
QrPayment payment = await session.Completion;
QrPaymentStatus status = payment.GetStatus(DateTimeOffset.Now);

// payment state by ID, for example after your software restarts
QrPayment? found = await qrPaymentService.FindPaymentAsync(transactionId, cancellationToken);
```

The session from step 1 tracks the payment state continuously. `FindPaymentAsync` returns `null` if the payment is
not found.

#### <span id="paymentstatus" class="anchor"></span>Payment states

The final states are `paid`, `overpaid` and `expired`. In the .NET library, `QrPaymentStatus` has the same values
starting with a capital letter (`Pending`, `Paid`, …).

| Value | Description |
|---|---|
| `pending` | The payment has been created, but no incoming payment has been received yet. |
| `partiallyPaid` | A partial payment has been received, but the full amount is not yet covered. |
| `paid` | The payment has been fully settled: the received amount equals the requested amount. |
| `overpaid` | The received amount exceeds the requested amount (overpayment). |
| `expired` | The payment has expired before being fully paid. |

```mermaid
stateDiagram-v2
    [*] --> pending
    pending --> partiallyPaid: part of the amount
    pending --> paid: full amount
    pending --> overpaid: more than the amount
    partiallyPaid --> paid: remainder paid
    partiallyPaid --> overpaid: more than the remainder
    pending --> expired: not paid
    partiallyPaid --> expired: not fully paid
    paid --> [*]
    overpaid --> [*]
    expired --> [*]
```

With `paid` and `overpaid`, register the receipt for the amount actually received; with `expired`, continue with
step 4.

### 4. Payment failure notice

If the confirmation does not arrive in time or the cashier stops waiting, the cash register must issue or make
available a **document of non-confirmation of the payment** ([§ 15(3) of Act No. 384/2025 Coll.](https://www.slov-lex.sk/ezbierky-fe/pravne-predpisy/SK/ZZ/2025/384/20260101#paragraf-15.odsek-3)). According to
the [Financial Administration](https://podpora.financnasprava.sk/121316-Bezhotovostn%C3%A1-platba), the mandatory data are the date and time the payment ID was generated, the
payment ID and the amount; the business's name and tax ID (DIČ) are optional. eKasa prints all of them, the name and
tax ID in the business header:

[Image: Payment failure notice: business header, the heading Potvrdenie k žiadosti o vrátenie okamžitej úhrady (confirmation for a request to return an instant payment), date and time the payment was created, transaction ID and amount]

**HTTP API:**

```http
POST {server_address}/api/v1/payments/qr/{transactionId}/print_non_delivery_notice
```

The request has no body. The response `204 No Content` means the notice is printed, `404 Not Found` that the payment
does not exist.

**.NET library:**

```csharp
if (status == QrPaymentStatus.Expired)
{
    await qrPaymentService.PrintPaymentNonDeliveryNoticeAsync(
        transactionId, cancellationToken);
}
```

If the payment does not exist, the method throws `QrPaymentNotFoundException`.

## Trying a payment

You can try a payment without writing any code in the eKasa web interface. In the integration environment, our test
utility pays it instead of a bank, so you can also try a partial payment or an overpayment. The procedure is in
[Setup and test](https://ekasa.ninedigit.sk/en/docs/qr-payments/environment-setup#payment-test).

**.NET library:**

## Full .NET example

The whole payment through the .NET library: creating it, printing the QR code, waiting for the result and the non-confirmation notice.

```csharp
IQrPaymentService qrPaymentService = client.QrPaymentService;

var request = new QrPaymentRequest(cashRegisterCode: "88812345678900001", amount: 19.90m);

// 1. ID
IQrPaymentSession session = await qrPaymentService.InitiatePaymentAsync(request, cancellationToken);
QrPaymentTransactionId transactionId = session.Payment.TransactionId;

// 2. QR
await qrPaymentService.RenderPaymentAsync(transactionId, QrPaymentRendererName.PosPrinter, cancellationToken);

// 3. Paid, Overpaid, Expired
QrPayment payment = await session.Completion;
QrPaymentStatus status = payment.GetStatus(DateTimeOffset.Now);

if (status == QrPaymentStatus.Expired)
{
    // 4. Payment not confirmed, printing the notice.
    await qrPaymentService.PrintPaymentNonDeliveryNoticeAsync(transactionId, cancellationToken);
}
else if (status == QrPaymentStatus.Overpaid)
{
    Console.WriteLine($"The customer overpaid by {payment.OverpaidAmount}.");
}
```

## Frequently asked questions

**Is a QR payment tied to a receipt?**

No. It is a separate process before receipt registration, and no receipt data is sent when the payment is created.
Once the payment is confirmed, your software registers the receipt.

**How long should I wait for the payment?**

The law does not specify it. From experience we recommend 90 seconds. You set the time in your software.

**What if the customer does not pay or the payment does not arrive in time?**

The cash register prints a receipt confirming the payment was not completed. The customer can then pay another way.

**Can the customer pay a different amount?**

It should not be possible. Under the payment link specification, the banking app does not let the customer change
the amount from the QR code. It cannot be ruled out completely, though: if someone deliberately edits the QR code,
for example changes the amount in it, and scans the edited code, a payment with a different amount arrives.

Your software must therefore be prepared for it and always work with the amount actually paid, from the
[payment status](#paymentstatus):

- `partiallyPaid`: only part has been paid and the payment is not settled yet. The customer can pay the rest with
  another QR code (the link for the remaining amount is in `links`) or another way.
- `overpaid`: more has been paid; the difference is in `overpaidAmount`. Your software must show the overpayment to
  the cashier so they can settle it with the customer, typically by returning it.

Register the receipt according to the amount actually received.

## Where next

- [Setup and test](https://ekasa.ninedigit.sk/en/docs/qr-payments/environment-setup): Setting up QR payments in eKasa.
- [Receipt registration](https://ekasa.ninedigit.sk/en/docs/receipt-registration): Register the receipt once the payment is confirmed.
- [QR payment errors](https://ekasa.ninedigit.sk/en/docs/rest-api/error-codes#-700-qrpaymenterror): Codes -700 to -702.
