Integrácia QR platieb

QR platby umožňujú uskutočnenie transakcie prostredníctvom QR kódu v eKase.

Odkazy

• PDF Verzia
• Potvrdenie QR platieb (integračné) - Webová aplikácia na simulovanie banky v integračnom prostredí.
• Overenie QR platby (integračné) - Webová aplikácia na overenie stavu QR platby

Integračný IBAN: SK4509000000000286241634 — majiteľ účtu: VAROS TRADE s.r.o.

Existujú dva hlavné prístupy k integrácii:

• optimálna
• jednoduchá

Optimálna integrácia

Pri tomto spôsobe úhrady dokladu sa najprv uskutoční platba pomocou QR kódu pomocou dotazu QVERKO. Následne podľa výsledku z notifikačného servera sa doklad buď vytlačí, alebo sa platba uskutoční pomocou iného typu platidla. Ak výsledok dotazu nepotvrdí zrealizovanie platby je možné do 2 hodín požiadať o notifikáciu pomocou dotazu NOTIFY.

Konfiguračné požiadavky

• V tomto prípade v konfigurácii eKasy nemôže byť vybraté platidlo, ktoré sa používa na úhradu QR kódom, aby si ho naša aplikácia sama neodchytávala.

Timeout nastavenia

FT5000

Len ak komunikujete cez tlačový manažér, nastavte v TM5000:

• Záložka Preberanie tlače → Time Info = 15 000 ms

FT4000

Nastaviť timeouty v TM5000WIN:

• Záložka Preberanie tlače → Time Info = 15 000 ms
• Záložka QR code → Bank Timeout = 60 000 ms

Timeout pokrýva čas potrebný na celý priebeh: získavianie identifikátora, zosnímanie QR mobilom, potvrdenie v bankovej aplikácii a vrátenie výsledku.

Identifikátor transakcie QrId

Odporúčame rozšíriť DB o stĺpec QrId – jednoznačný identifikátor transakcie notifikačného servera FS.

• Identifikátor QrId by mal byť uvedený aj na bankovom výpise na identifikáciu platby
• Identifikátor QrId sa použije pri reklamácii alebo dohľadaní platby
• Príklad: QR-ab29e346f1d841c8a95a63d857490818

Tok transakcie

• Predajná aplikácia si pred tlačou dokladu vyžiada uskutočnenie QR platby cez eKasu.

• eKasa zobrazí / vytlačí QR kód na zosnímanie mobilom na vykonanie platby.

• Predajná aplikácia si počká na odpoveď z eKasy.

  • Poznámka: Pri transakcii sa vykonáva postupnosť úkonov a treba počítať s dlhšou dobou čakania na odpoveď:
    1. Získanie a zobrazenie identifikátora QR platby
    2. Zosnímanie QR kódu mobilom
    3. Potvrdenie platby v bankovej aplikácii
    4. Prevedenie platby z banky kupujúceho do banky predávajúceho
    5. Verifikácia platby bankou
    6. Verifikácia platby eKasou pomocou notifikačného servera
    7. Odoslanie odpovede do PC

• Po verifikácii platby predajná aplikácia vystaví doklad, ktorý má v platidle určenom na evidenciu QR platieb výšku uhradenej sumy. Evidovaná suma sa použije pri vyčíslení a následnej tlači uzávierok.

• Ak sa nepodarí verifikovať platbu, predajná aplikácia by mala ponúknuť iný typ úhrady dokladu.

Predajná aplikácia	Mobil	Banková aplikácia
Vyžiadanie QR platby eKASA - zobrazenie QR kódu	Odfotografovanie QR kódu Klikom na odkaz sa spustí banková aplikácia	Zobrazenie platby Kupujúci - kontrola a potvrdenie platby

Jednoduchá integrácia

Tento spôsob je možné použiť pri predajných aplikáciách s minimálnou úpravou programu. Predĺži sa čas čakania na odpoveď a QR platbe sa priradí v konfigurácii zodpovedajúce platidlo.

Konfiguračné požiadavky

• V konfigurácii eKasy musí byť vybraté platidlo, ktoré sa používa na úhradu QR kódom.

Timeout nastavenia

FT5000

Len ak komunikujete cez tlačový manažér, nastavte v TM5000:

• Záložka Preberanie tlače → Time Info = 90 000 ms

FT4000

Nastaviť timeouty v TM5000WIN:

• Záložka Preberanie tlače → Time Info = 90 000 ms
• Záložka QR code → Bank Timeout = 60 000 ms (rovnako ako pri optimálnej integrácii)

Výhody a nevýhody

• Výhoda: Minimálna úprava programu
• Nevýhoda: Najprv sa odošle doklad a následne sa predajná aplikácia dozvie, či platba prebehla v poriadku.

Tok transakcie

• Predajná aplikácia odošle do tlačiarne doklad, kde v zvolenom platidle pošle hodnotu QR platby.
• Ak sa v doklade nachádza platidlo QR platby, eKasa zobrazí / vytlačí QR kód na zosnímanie mobilom.
• eKasa verifikuje platbu:
  • Ak je verifikácia úspešná → vytlačí sa pokladničný doklad
  • Ak sa platbu nepodarí verifikovať → zobrazí / vytlačí sa chybové hlásenie s číslom chyby
  • Poznámka: Pri verifikácii treba rátať s dlhšou dobou odpovede
• Predajná aplikácia si vyčíta info o doklade: ESC I alebo ESC ! I
• Ak doklad skončí s chybou, predajná aplikácia by mala vystaviť nový doklad a ponúknuť iný typ úhrady.

Poznámka (FT4000): Pri jednoduchej integrácii a správne nakonfigurovanom TM5000WIN je možné banku simulovať priamo cez rozhranie tlačového manažéra bez externej aplikácie.

Typy QR platieb

Varos eKasa podporuje nasledujúce typy QR platieb:

QVERKO

Tento typ platby sa použije na uskutočnenie okamžitej úhrady pokladničného dokladu alebo úhrady faktúry pomocou QR kódu podľa nového zákona o registračných pokladniciach. Predajná aplikácia si pred tlačou dokladu vyžiada uskutočnenie QR platby cez eKasu pomocou príkazu QVERKO. Na základe požiadavky eKasa zobrazí / vytlačí výzvu na vykonanie QR platby a stanovenú dobu čaká na potvrdenie platby z Notifikátora platieb. eKasa automaticky vráti informáciu k danej platbe. Ak je odpoveď kladná predajná aplikácia vystaví doklad. Ak platba neprepehne do danej doby, predajná aplikácia má možnosť overiť si danú transakciu pomocou dotazu NOTIFY s pôvodným QR identifikátorom alebo použije na úhradu iný typ platidla.

• Výška platby je obmedzená limitom, aký má nastavený kupujúci vo svojej banke
• Vykonaná úhrada sa považuje za bezhotovostný spôsob úhrady dokladu

Právne obmedzenia na doklad:

PAYME

Okamžitá bezhotovostná úhrada faktúry. Tento typ úhrady nepodlieha zákonu o registračných pokladniciach a ani sa netlačí žiaden pokladničný doklad. Slúži na rýchle vykonanie úhrady faktúry. Zosnímaním QR kódu si mobilná banková aplikácia automaticky predplní údaje z faktúry potrebné na vykonanie platby názov a účet predávajúceho, suma k úhrade, VS, KS, SS

• Informácie o vykonanej úhrade príde na mobil majiteľa účtu k danému IBANu
• eKasa nemá notifikáciu o danej platbe
• Výška platby je obmedzená iba limitom, aký má nastavený kupujúci vo svojej banke na bankové transakcie

QRCODE

Vyžiadanie QR identifikátora platby ku konkrétnej eKase z API servera a následné vygenerovanie payme reťazca, ktorý obsahuje všetky informácie na vykonanie QR platby. Reťazec môže použiť predajná aplikácia kvôli vlastnému zobrazeniu QR platby na monitore počítača, alebo inom zariadení.

• Predajná aplikácia môže generovaný reťazec použiť na vlastné zobrazenie QR kódu na monitore počítača, alebo monitore samoobslužného automatu
• Následne po uskutočnení platby mobilnou aplikáciou banky sa musí volať dotaz NOTIFY na overenie zrealizovania QR platby eKasou

NOTIFY

Overenie zrealizovania QR platby na základe QR identifikátora. Notifikácia je možná maximálne 2 hodiny od realizovania platby.

• Slúži na overenie stavu vykonanej QR platby
• Používa sa identifikátor transakcie QrId

⚠️ Dôležité: Hodnota Value v dotaze NOTIFY musí byť zhodná s hodnotou použitou pri vytvorení QR kódu, pretože sa overuje kontrolný súčet platby.

DISPLAY

Funkcia zákazníckeho displeja – zobrazenie dvojriadkového textu alebo ľubovoľného QR kódu na dispeji.

• Možnosť použiť QR kód napríklad na presmerovanie na e-shop alebo internetovú stránku predávajúceho
• Pri tejto funkcii sa nevracia žiadna JSON odpoveď – vráti sa iba potvrdenie: ACK NULL NULL - 0x06 0x00 0x00
• Pri chybe sa vráti: NAK - 0x15

Opätovné zobrazenie QR kódu

Ak zákazník nestihol načítať QR kód, je možné ho opätovne zobraziť pomocou dotazu DISPLAY naplneného hodnotami z predchádzajúceho dotazu QVERKO. Následne je nutné volať NOTIFY na overenie zrealizovania platby.

Platnosť QR kódu je 2 hodiny od jeho vygenerovanie.

Vstupné a výstupné súbory

Vstup

blocek.txt

Výstup

info.txt
info.json
fm_sts.bin

info.txt vs info.json

Odporúčanie: Po každom doklade čítajte info.json a kontrolujte:

• Zvýšenie čísla dokladu oproti poslednému
• Stav dokladu
• Uložte UID (jedinečné číslo dokladu pridelené finančnou správou)
• Uložte QR Id pre prípadnú reklamáciu alebo overenie platby

JSON API

JSON rozhranie obsahuje dva súbory:

• QR-REQUEST - Odoslanie požiadavky na QR platbu
• QR-RESPOND - Odpoveď na požiadavku sa vráti automaticky

QR-REQUEST

Odoslanie požiadavky na QR platbu

• Syntax: <ESC>QR-REQUEST<ESC>e

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "QVERKO",  
  "Id": "PQR251200001",
  "QrId": "QR-ab29e346f1d841c8a95a63d857490818",
  "Line1": "Celkom EUR",
  "Line2": "     25.00",
  "Value": "25.00",
  "QrCode": {
    "data": "qrData",
    "printOnPrn": false,
    "showOnDsp": true,
    "timeout": 30
  },
  "Bank": {
    "VS": "202500053",
    "SS": "",
    "KS": "0008",
    "Msg": "Platba Faktury"
  }
}

Premenná type v JSON formáte definuje význam JSON príkazu. V závislosti na premennej type sú vyžadované premenné podľa nasledujúcej tabuľky.

Legenda:

• 1 - premenná sa musí vyplniť
• 0/1 - premenná sa použije ak je vyplnená (ak sa neuvedie a je potrebná, naplní sa údajom z konfigurácie eKasy)
• 0 - premenná sa pri spracovaní nepoužije

QR-RESPOND

Odpoveď na požiadavku sa vráti automaticky

• Syntax: ACK + počet znakov odpovede QR-RESPOND + odpoveď QR-RESPOND
• Chybový stav: Pri chybe sa vráti NAK - 0x15

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "QVERKO",
  "Id": "PQR251200001",
  "QrId": "QR-ab29e346f1d841c8a95a63d857490818",
  "QrCode": "https://payme.sk/?V=1&IBAN=SK4509000000000286241634&AM=25.00&CC=EUR&PI=%2FVS%2FSS%2FKS0008&MSG=Platba+Faktury&CN=Varos+Trade",  
  "Value": "0.00",
  "Date": "2025-09-17",
  "Time": "15:30:55",
  "IBAN": "SK4509000000000286241634",
  "errCode": 1,
  "errMsg": "textový popis chybovej správy"
}

Na základe premennej type vo vstupnom JSON formáte sa vrátia jednotlivé premenné v JSON odpovedi podľa nasledujúcej tabuľky.

Legenda:

• 1 - premenná bude vyplnená
• 0 - premenná sa nevyplní

Príklady

V nasledujúcich príkladoch sú uvedené JSON požiadavky a odpovede pre jednotlivé typy QR platieb.

QVERKO

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "QVERKO",  
  "Id": "PQR251200001",
  "Value": "25.00",
  "QrCode": {
    "printOnPrn": false,
    "showOnDsp": true,
    "timeout": 30
  },
  "Bank": {
    "Msg": "Pokladnicny doklad 25123100069"
  }
}

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "QVERKO",
  "Id": "PQR251200001",
  "QrId": "QR-ab29e346f1d841c8a95a63d857490818",
  "Value": "25.00",
  "Date": "2025-09-17",
  "Time": "15:30:55",
  "IBAN": "SK4509000000000286241634",
  "errCode": 1,
  "errMsg": "textovy popis chybovej spravy"
}

PAYME

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "PAYME",  
  "Id": "PQR251200001",
  "Value": "25.00",
  "QrCode": {
    "printOnPrn": false,
    "showOnDsp": true,
    "timeout": 30
  },
  "Bank": {
    "IBAN": "SK4509000000000286241634",
    "VS": "202500053",
    "SS": "122025",
    "KS": "0008",
    "Msg": "Bezhotovostna uhrada Faktury"
  }
}

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "PAYME",
  "Id": "PQR251200001",
  "Value": "15000.00",
  "IBAN": "SK4509000000000286241634"
}

QRCODE

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "QRCODE",  
  "Id": "PQR251200001",
  "Value": "25.00",
  "Bank": {
    "Msg": "Pokladnicny doklad 25123100069"
  }
}

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "QRCODE",
  "Id": "PQR251200001",
  "QrId": "QR-ab29e346f1d841c8a95a63d857490818",
  "QrCode": "https://payme.sk/?V=1&IBAN=SK4509000000000286241634&AM=25.00&CC=EUR&PI=%2FVS%2FSS%2FKS0008&MSG=Platba+Faktury&CN=Varos+Trade",  
  "Value": "25.00",
  "IBAN": "SK4509000000000286241634",
  "errCode": 1,
  "errMsg": "textový popis chybovej správy"
}

NOTIFY

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "NOTIFY",
  "Id": "PQR251200001",
  "QrId": "QR-ab29e346f1d841c8a95a63d857490818",
  "Value": "25.00"
}

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "NOTIFY",
  "Id": "PQR251200001",
  "QrId": "QR-ab29e346f1d841c8a95a63d857490818",
  "Value": "25.00",
  "Date": "2025-09-17",
  "Time": "15:30:55",
  "IBAN": "SK4509000000000286241634",
  "errCode": 1,
  "errMsg": "textový popis chybovej správy"
}

DISPLAY

{
  "ReceiptFormat": "VAROS_JSON",
  "Version": "1.0.0",
  "ReceiptType": "QR",
  "type": "DISPLAY",  
  "Line1": "Akciova   ",
  "Line2": "ponuka    ",
  "QrCode": {
    "data": "https://www.varos.sk/EKASA_SK/2026_Nove_legislativne_povinnosti.pdf",
    "showOnDsp": true,
    "timeout": 30
  }
}