Pro vývojáře

Dokumentace QR Pay

Vše co potřebujete k integraci QR Pay do vašeho e-shopu. Celá integrace trvá méně než 5 minut.

Quickstart

Pro základní integraci potřebujete pouze váš API klíč z dashboardu a dva řádky HTML.

1. Vytvořte objednávku přes API

POST https://api.qrpay.cz/v1/orders
Authorization: Bearer qrp_live_xxxxxxxxxxxx
Content-Type: application/json

{
  "amount_czk": 1299.00,
  "message": "Objednavka #1234",
  "webhook_url": "https://vas-eshop.cz/webhook/qrpay"
}

// Response:
{
  "order_id": "ord_abc123",
  "vs": "2024061203",
  "widget_url": "https://widget.qrpay.cz/ord_abc123",
  "expires_at": "2026-06-09T16:32:00Z"
}

2. Vložte widget do checkoutu

<!-- Přidejte do stránky jednou -->
<script src="https://cdn.qrpay.cz/widget.js" defer></script>

<!-- Vložte tam, kde má QR kód být vidět -->
<div id="widget" data-qrpay-order="ord_abc123"></div>

3. Zpracujte webhook notifikaci

// Node.js / Express příklad
app.post('/webhook/qrpay', (req, res) => {
  const sig = req.headers['x-qrpay-signature'];
  const body = req.rawBody; // raw string

  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.QRPAY_WEBHOOK_SECRET)
    .update(body)
    .digest('hex');

  if (sig !== expected) return res.status(401).end();

  const { event, order_id, amount_czk } = req.body;
  if (event === 'payment.confirmed') {
    // ✓ Platba ověřena — dokončete objednávku
    await fulfillOrder(order_id);
  }
  res.status(200).end();
});

Widget

Widget automaticky zobrazí QR kód, odpočítávač a stav platby v reálném čase.

Data atributy

data-qrpay-orderrequired

string

ID objednávky vrácené z POST /v1/orders

data-qrpay-theme

light | dark

Světlý nebo tmavý motiv widgetu (výchozí: light)

data-qrpay-lang

cs | en

Jazyk widgetu (výchozí: cs)

data-qrpay-redirect

string

URL pro přesměrování po potvrzení platby

JavaScript events

const el = document.getElementById('widget');

el.addEventListener('qrpay:confirmed', (e) => {
  console.log('Zaplaceno:', e.detail.order_id);
  window.location.href = '/objednavka-dokoncena';
});

el.addEventListener('qrpay:expired', () => {
  console.log('Platba expirovala — zobrazit nový QR');
});

REST API

Base URL: https://api.qrpay.cz/v1

POST/ordersVytvořit novou objednávku

GET/orders/:idStav objednávky (pending / paid / expired)

POST/orders/:id/cancelZrušit objednávku

GET/ordersSeznam objednávek (stránkovaný)

Webhooks

QR Pay odesílá webhook notifikaci při každé změně stavu objednávky. Payload je podepsán HMAC-SHA256.

Dostupné eventy

payment.confirmedPlatba byla ověřena — VS i částka souhlasí

payment.expiredObjednávka expirovala bez platby (po 2 hodinách)

payment.cancelledObjednávka byla ručně zrušena

JS SDK

Pro Node.js máme officiální SDK s plnou TypeScript podporou.

npm install @qr-pay/sdk

import { QRPayClient } from '@qr-pay/sdk';

const client = new QRPayClient({
  apiKey: process.env.QRPAY_API_KEY,
});

// Vytvořit objednávku
const order = await client.orders.create({
  amountCzk: 1299,
  message: 'Objednavka #1234',
  webhookUrl: 'https://vas-eshop.cz/webhook/qrpay',
});

console.log(order.widgetUrl);
// → https://widget.qrpay.cz/ord_abc123