Pro vývojáře

Dokumentace

Vše, co potřebujete k integraci BezBrany do svého e-shopu. Kompletní API referenci najdete ve Swagger dokumentaci.

Rychlý start

1
Zaregistrujte se a vytvořte merchant účet

Po přihlášení vás provede onboarding — vyplníte základní údaje a přidáte bankovní účet s Fio API tokenem.
2
Vygenerujte si API klíč

V administraci v sekci Nastavení → API klíče. Pro testování použijte test klíč — platby lze simulovat bez skutečných peněz.
3
Vytvořte první platbu

Zavolejte API s klíčem v hlavičce X-API-Key — odpověď obsahuje QR kód i platební kód pro widget.

REST API reference

Metoda	Endpoint	Popis
POST	/api/v1/payments	Vytvoření platby (API klíč)
GET	/api/v1/payments/{paymentCode}	Stav platby (API klíč)
POST	/api/v1/payments/{paymentCode}/simulate-success	Simulace úspěchu (jen test klíče)
POST	/api/v1/widget/payments	Vytvoření platby z frontendu (veřejný pk_ klíč, hlavička X-Public-Key)
GET	/api/v1/widget/payments/{paymentCode}	Stav platby pro widget
GET	/api/v1/merchants/me/payments	Seznam plateb (Bearer token)
GET	/api/v1/merchants/me/payments/export	CSV export plateb (Bearer token)

Příklad vytvoření platby:

create-payment.sh

curl -X POST https://api.bezbrany.cz/api/v1/payments \
  -H "X-API-Key: VAS_API_KLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "CZK",
    "orderNumber": "OBJ-2026-001",
    "payer": { "contact": { "firstName": "Jan", "lastName": "Novák", "email": "jan@example.cz" } },
    "items": [{ "name": "Tričko", "amount": 100, "quantity": 1 }]
  }'

Widget integrace

Nejjednodušší způsob integrace — vložte skript a kontejner do HTML. Widget zobrazí QR kód, sleduje stav platby v reálném čase a po zaplacení zobrazí potvrzení.

index.html

<script src="https://api.bezbrany.cz/widget/v1.js"></script>
<div data-bezbrany-widget data-payment-code="VAS_PLATEBNI_KOD"></div>

Podporované data-* atributy:

data-bezbrany-widget — označí kontejner widgetu
data-payment-code — kód platby získaný z API

Alternativně lze widget inicializovat programaticky přes BezBranyWidget.init({ paymentCode, containerId, onPaymentSuccess }).

Webhooky

Po dokončení platby odešleme POST request na vaši webhook URL (nastavíte v profilu merchanta nebo per platba přes callback.notificationUrl). Payload:

webhook-payload.json

{
  "id": "b7c3e1a2-...",
  "event": "payment.completed",
  "createdAt": "2026-07-24T10:12:30.000Z",
  "paymentId": "uuid",
  "paymentCode": "A1B2C3D4E5F6A7B8",
  "orderNumber": "OBJ-2026-001",
  "status": "completed",
  "amount": 100,
  "currency": "CZK",
  "metadata": {}
}

Pole id je unikátní pro každé doručení — použijte ho k deduplikaci (opakované doručení má stejné id). Podle event filtrujte typ události; ignorujte neznámé typy, ať vás nerozbijí budoucí události.

Každý webhook je podepsán HMAC SHA-256 pomocí vašeho webhook secretu. Ověření podpisu:

verify-webhook.js

// Hlavička: X-BezBrany-Signature: t=<timestamp>,v1=<podpis>
const crypto = require('crypto');

function verifyWebhook(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(
    signatureHeader.split(',').map(p => p.split('='))
  );
  const signedPayload = `${parts.t}.${rawBody}`;
  const expected = crypto.createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(parts.v1)
  );
}

Při selhání doručení webhook opakujeme s exponenciálním rozestupem (1 min → 5 min → 30 min → 2 h).