QR Platby
Tento článok popisuje interakciu so systémom prevádzkovaným Fiančnou správou v rámci projektu QR platieb, NOP (Noifikátor okamžitých platieb).
Realizácia QR platby spočíva v troch krokoch:
1. Získanie ID platby
Každá QR platba je identifikovaná jedinečným identifikátorom platby (ďalej len ID platby).
Prvým krokom realizácie QR platby je preto získanie takéhoto identifikátora.
ID platby generuje systém Finančnej správy.
🔗 API koncový bod pre získanie ID platby
Tip
Nadradená aplikácia by si mala ID platby uchovať pre prípad, že nastane chyba v ďalšom procese spracovania platby. Stav platby je možné opakovane získať práve na základe ID platby.
2. Zobrazenie QR kódu
Aby mohol kupujúci platbu v danej uhradiť, musí mu byť poskytnutý QR kód na nasmínamie. Štandardne sa predpokladá, že kupujúci QR kód nasníma fotoaparátom svojho smartfónu pre úhradu cez internet banking aplikáciu, ktorá je nainštalovaná a aktivovaná na smartfóne.
Zobrazenie QR kódu môže byť realizované nadradenou (predajnou) aplikáciou, alebo priamo eKasou.
2.1 Zobrazenie QR kódu nadradenou aplikáciou
QR kód môže kupujúcemu vyobraziť nadradená (predajná) aplikácia podľa dostupných technických prostriedkov (napríklad na displeji zariadenia či grafickom zákazníckom displej).
Obsahom QR kódu, ktorý je potrebné kupujúcemu zobraziť, je platobná linka Payme podľa štandardu SBA, ktorá sa nachádza vo vlastnosti links odpovede na API metódu pre získanie ID platby.
2.2 Zobrazenie QR kódu eKasou
V prípade, ak nadradená aplikácia nemá technické možnosti zobrazenia QR kódu kupujúcemu, QR kód dokáže vybraziť niektorou z podporovaných metód aj priamo eKasa aplikácia.
🔗 API koncový bod pre zobrazenie QR kódu
3. Čakanie na platbu
Po zobrazení QR kódu kupujúcemu nadradená aplikácia čaká na realizáciu platby vyvolaním HTTP požiadavky pre získanie aktuálneho stavu platby alebo čakanie na výsledok platby.
🔗 API koncový bod pre získanie QR platby
Tip
Simulácia platby
Pre simuláciu platby v integračnom prostredí použite našu testovaciu utilitu.
Postup:
- Spustite aplikaciu
NineDigit.eKasa.QrPayment.exe.
- Aplikácia vás správou Please enter payme v2 URL vyzve na vloženie platobného odkazu.
- Aplikácia vám umožní upraviť sumu na úhradu (pre simuláciu čiastočnej či presahujúcej platby). Pre zachovanie pôvodnej čiastky stlačte kláves
ENTER.
- Hotovo. 🎉 Úspešné odoslanie platby je sprevádzané hlásením Notification sent successfully..
3.1 Tlač oznámenia o neúspešnej platbe
V prípade, ak notifikácia o platbe nie je doručená v časovom limite, pokladnica je zo zákona (§15 bod 3 zákona o evidencii tržieb) povinná vytlačiť o tejto skutočnosti doklad, ktorý sa označuje ako doklad o nepotvrdení zrealizovanej platby.
Doklad musí obsahovať najmenej tieto údaje:
- dátum a čas vytvorenia ID platby (vlastnosť
createdAt modelu qrPayment)
- ID platby (vlastnosť
transactionId modelu qrPayment)
- suma neúspešnej úhrady v EUR (vlastnosť
amount modelu qrPayment)
- názov firmy podľa ORSR
- daňové identifikačné číslo (DIČ) predajcu
Pre vytlačenie dokladu je k dispozícii API koncový bod.
🔗 API koncový bod pre tlač oznámenia o neúspešnej platbe
QR Payments
This article describes the interaction with the system operated by the Financial Administration as part of the QR Payments project, the NOP (Instant Payments Notifier).
The process of making a QR payment consists of three steps:
1. Obtaining a Payment ID
Each QR payment is identified by a unique payment identifier (Payment ID).
The first step in processing a QR payment is therefore to obtain this identifier.
The Payment ID is generated by the Financial Administration system.
🔗 API endpoint for obtaining a Payment ID
Tip
The parent (sales) application should store the Payment ID in case an error occurs during the subsequent payment processing steps. The payment status can always be re-queried using this Payment ID.
2. Displaying the QR Code
To allow the buyer to make the payment, a QR code must be displayed for scanning. It is typically assumed that the buyer will scan the QR code using the camera of their smartphone to initiate payment via their mobile banking app.
The QR code can be displayed either by the parent (sales) application or directly by the eKasa application.
2.1 Displaying the QR Code by the Parent Application
The parent (sales) application can render the QR code for the buyer using any available display mechanism — such as the main device screen or an external customer display.
The content of the QR code that must be shown to the buyer is a Payme payment link following the SBA standard, which can be found in the links property of the response from the API method for obtaining a Payment ID.
2.2 Displaying the QR Code by eKasa
If the parent application does not have the technical capability to display a QR code to the buyer, the eKasa application itself can render the QR code using one of its supported methods.
🔗 API endpoint for rendering the QR code
3. Waiting for the Payment
After the QR code is displayed to the buyer, the parent application waits for the payment to be made by calling the HTTP endpoint to retrieve the current payment status or to wait for the payment to complete.
🔗 API endpoint for getting QR payment status
Tip
Payment Simulation
To simulate a payment in the integration environment, use our test utility.
Procedure:
- Launch the application
NineDigit.eKasa.QrPayment.exe.
- The application will prompt you with the message Please enter payme v2 URL to enter the payment link.
- The application allows you to adjust the payment amount (to simulate partial or excessive payments). To keep the original amount, press the
ENTER key.
- Done. 🎉 Successful payment submission is accompanied by the message Notification sent successfully.
3.1 Printing a Payment Failure Notice
If the payment notification is not delivered within the specified time limit, the cash register is legally required (§15, paragraph 3 of the Act on Revenue Records) to print a document acknowledging this fact, referred to as a receipt of unconfirmed completed payment (doklad o nepotvrdení zrealizovanej platby).
The document must include the following information:
- the date and time when the payment ID was created (property
createdAt of the qrPayment model)
- the payment ID (property
transactionId of the qrPayment model)
- the amount of the unsuccessful payment in EUR (property
amount of the qrPayment model)
- the company name as registered in the Business Register (ORSR)
- the company tax identification number (DIČ)
An API endpoint is available for printing this document.
🔗 API endpoint for printing the receipt of unconfirmed completed payment