Od QR kódu k potvrzení
za méně než 60 sekund

V Fio Internet Bankingu vygenerujete read-only API token. Token umožňuje pouze čtení výpisů z účtu přes REST API — žádné odchozí platby nejsou možné.

Token zadáte do QR Pay dashboardu jednou. My jej uložíme šifrovaně přes Supabase Vault (pgsodium / AES-256-GCM) — nikdo ho nemůže přečíst v plaintextu.

Fio API endpoint

GET /v1/rest/periods/{token}/{dateFrom}/{dateTo}/transactions.json

// Rate limit: min. 30 sekund mezi requesty
// Response: { accountStatement: { transactionList: [...] } }
// column5 = VS, column1 = částka

Widget vložíte do e-shopu dvěma řádky JavaScriptu. Při vytvoření objednávky zavoláte naše API a dostanete URL widgetu.

Widget zobrazí QR kód ve formátu SPD (Short Payment Descriptor) — standardu pro QR platby v ČR. Zákazník zaplatí přes mobilní banku jedním skenem.

Každá platba má unikátní variabilní symbol (VS) — 10místné číslo generované z timestampu. Při ověření kontrolujeme VS i částku zároveň.

SPD formát

SPD*1.0*
ACC:CZ6520100000002000160517+FIOBCZPPXXX*
AM:1299.00*
CC:CZK*
X-VS:2024061203*
MSG:Objednavka 1234

Embed snippet

<script src="https://cdn.qrpay.cz/widget.js"></script>
<div data-qrpay-order="ord_abc123"></div>

QR Pay periodicky volá Fio API (každých 30 sekund — minimální interval Fio). Pro každou příchozí transakci ověřujeme:

• VS (variabilní symbol) se shoduje s čekající objednávkou
• Částka se shoduje přesně (tolerance 0,001 Kč)
• Transakce přišla po vzniku objednávky

Objednávka expiruje po 2 hodinách. Pokud platba nedorazí včas, stav se změní na expired.

Matching logika

// Oba parametry musí souhlasit
if (tx.column5?.value === order.vs &&
    Math.abs(tx.column1.value - amountCzk) < 0.001) {
  // ✓ Platba ověřena
  await markOrderPaid(order.id, tx.transactionId);
}

Jakmile je platba potvrzena, zavoláme váš webhook URL. Notifikace obsahuje HMAC-SHA256 podpis v hlavičce X-QRPay-Signature.

Webhook se opakuje max. 5 krát s exponenciálním backoffem, pokud váš server nevrátí HTTP 2xx.

Webhook payload

POST https://vas-eshop.cz/webhook/qrpay
X-QRPay-Signature: sha256=abc123...

{
  "event": "payment.confirmed",
  "order_id": "ord_abc123",
  "vs": "2024061203",
  "amount_czk": 1299.00,
  "paid_at": "2026-06-09T14:32:11Z"
}