Získanie ID platby

HTTP metóda

POST

URL

{server_address}/api/v1/payments/qr

Požiadavka

Hlavičky

Kľúč	Hodnota	Popis
`Content-Type`	`application/json`	Telo požiadavky je vo formáte JSON.

Telo požiadavky

Názov	Typ	Povinné	Popis
`amount`	`number`	Áno	Suma platby. Kladné nenulové číslo s presnosťou najviac na dve desatinné miesta.
`cashRegisterCode`	`string`	Áno	Kód pokladnice (napr. 88812345678900001).
`comment`	`string?`	Nie	Voliteľná textová poznámka k platbe, zasielaná do notifikátora okamžitých platieb (NOP) počas generovania ID platby.
`recipientMessage`	`string?`	Nie	Voliteľná správa pre príjemcu platby, prenášaná v platobnom odkaze QR platby. Ak nie je uvedená, použije sa hodnota z nastavení aplikácie.

Príklad

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

Odpoveď

Odpoveď HTTP 201 (Created)

Hlavičky

Kľúč	Hodnota	Príklad
`Location`	Adresa, na ktorej je možné získať informácie o vytvorenej platbe.	`{server_address}/api/v1/payments/qr/QR-5aab8a57dbf34436bb642ed76c249ab1`

Telo odpovede (JSON)

Dátový model QrPayment

{
    "transactionId": "QR-060fbdf7a1404366ac712e396d9d1052",
    "amount": 19.90,
    "currencyCode": "EUR",
    "merchant": {
        "iban": "SK4811000000002944116480",
        "name": "Merchant Name, s.r.o."
    },
    "cashRegisterCode": "88812345678900001",
    "createdAt": "2025-10-31T17:41:21+01:00",
    "expiresAt": "2025-10-31T17:43:21+01:00",
    "payments": [],
    "status": "pending",
    "paidAmount": 0.00,
    "remainingAmount": 19.90,
    "overpaidAmount": 0.00,
    "recipientMessage": "eKasa QR platba",
    "links": [
        {
            "provider": "payme",
            "version": "1.3",
            "url": "https://payme.sk/?V=1&IBAN=SK4811000000002944116480&AM=19.90&CC=EUR&CN=Merchant+Name%2C+s.r.o."
        },
        {
            "provider": "payme",
            "version": "2.0",
            "url": "https://payme.sk/2/m/PME?IBAN=SK4811000000002944116480&AM=19.90&CC=EUR&PI=QR-060fbdf7a1404366ac712e396d9d1052&CN=Merchant+Name%2C+s.r.o."
        }
    ]
}

Odpoveď HTTP 500

Chyba vytvorenia QR platby

Ak je v odpovedi je kód chyby (vlastnosť code) nastavená na -701, ide o chybu vytvorenia QR platby.

QR platbu sa nepodarilo vytvoriť a požiadavku je potrebné opakovať.

{
    "traceId": "0HNGIPOQC63UF:00000002",
    "code": -701,
    "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-701-qrpaymentinitializationerror",
    "title": "Chyba vytvorenia QR platby",
    "status": 500,
    "detail": "Nepodarilo sa nadviazať sieťové spojenie so službou okamžitých platieb.",
    "instance": "/api/v1/payments/qr",
    "extensions": {}
}

Getting a Payment ID

HTTP Method

POST

URL

{server_address}/api/v1/payments/qr

Request

Headers

Key	Value	Description
`Content-Type`	`application/json`	The request body is JSON.

Request Body

Name	Type	Required	Description
`amount`	`number`	Yes	Payment amount. A positive non‑zero number with up to two decimal places.
`cashRegisterCode`	`string`	Yes	Cash register code (e.g., 88812345678900001).
`comment`	`string?`	No	Optional text note for the payment, sent to the Instant Payments Notifier (NOP) during payment ID generation.
`recipientMessage`	`string?`	No	Optional message for the payment recipient, included in the QR payment link. If not specified, the value from the application settings is used.

Example

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

Response

HTTP 201 (Created)

Headers

Key	Value	Example
`Location`	URL where the created payment can be queried.	`{server_address}/api/v1/payments/qr/QR-5aab8a57dbf34436bb642ed76c249ab1`

Response Body (JSON)

Data model QrPayment

{
    "transactionId": "QR-060fbdf7a1404366ac712e396d9d1052",
    "amount": 19.90,
    "currencyCode": "EUR",
    "merchant": {
        "iban": "SK4811000000002944116480",
        "name": "Merchant Name, s.r.o."
    },
    "cashRegisterCode": "88812345678900001",
    "createdAt": "2025-10-31T17:41:21+01:00",
    "expiresAt": "2025-10-31T17:43:21+01:00",
    "payments": [],
    "status": "pending",
    "paidAmount": 0.00,
    "remainingAmount": 19.90,
    "overpaidAmount": 0.00,
    "recipientMessage": "eKasa QR platba",
    "links": [
        {
            "provider": "payme",
            "version": "1.3",
            "url": "https://payme.sk/?V=1&IBAN=SK4811000000002944116480&AM=19.90&CC=EUR&CN=Merchant+Name%2C+s.r.o."
        },
        {
            "provider": "payme",
            "version": "2.0",
            "url": "https://payme.sk/2/m/PME?IBAN=SK4811000000002944116480&AM=19.90&CC=EUR&PI=QR-060fbdf7a1404366ac712e396d9d1052&CN=Merchant+Name%2C+s.r.o."
        }
    ]
}

HTTP 500

QR Payment Initialization Error

If the error code (code property) is -701, this indicates a QR payment initialization error.

The QR payment could not be created and the request should be retried.

{
    "traceId": "0HNGIPOQC63UF:00000002",
    "code": -701,
    "type": "https://ekasa.ninedigit.sk/docs/webapi/apierrorcodes.html#-701-qrpaymentinitializationerror",
    "title": "QR payment initialization error",
    "status": 500,
    "detail": "Failed to establish a network connection to the instant payments service.",
    "instance": "/api/v1/payments/qr",
    "extensions": {}
}