Obsah

API pro e-shopy

Stejný párovací motor jako na terminálu, jen pro váš e-shop: vystavíte platbu, zobrazíte QR v košíku a webhook vám do pár desítek sekund potvrdí zaplacení.

Klíče

API klíče

Správce vytvoří API klíč — token se zobrazí jen jednou, uložte si ho hned. Ke klíči patří i webhook secret pro ověřování podpisů (ten jde zobrazit opakovaně). Klíče se nemažou, jen deaktivují — historie plateb na ně odkazuje.

Vystavení platby

POST /api/v1/payment_requests
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 250,
  "reference": "objednavka-123",
  "webhook_url": "https://vas-eshop.cz/jenqr-webhook",
  "expires_in": 1800,
  "customer": { "name": "Firma s.r.o.", "ico": "12345678",
                "dic": "CZ12345678", "address": "Dlouhá 1, Praha" },
  "line_items": [ { "title": "Zboží", "price": 250, "qty": 1, "vat_rate": 21 } ]
}

Povinná je jen částka. reference (vaše číslo objednávky) a webhook_url chcete prakticky vždy. expires_in je 300–3600 sekund, výchozích 600. customer a line_items jsou volitelné — se zadaným odběratelem vyjde doklad jako faktura, s položkami je položkový. Sazba DPH smí být 21, 12 nebo 0.

Odpověď (201) vrací id, vs, status a spayd — řetězec QR Platby, ze kterého vykreslíte QR kód. Stav zjistíte kdykoli přes GET /api/v1/payment_requests/<id> (spayd vrací, jen dokud má smysl platit).

Webhook

Při změně stavu (paid, partially_paid, expired) pošleme POST na vaši URL. Tělo podepisujeme hlavičkou X-Jenqr-Signature — HMAC-SHA256 surového těla webhook secretem:

expected = OpenSSL::HMAC.hexdigest("SHA256", webhook_secret, request_body)
valid = Rack::Utils.secure_compare(expected, request.headers["X-Jenqr-Signature"])

Doručení opakujeme s odstupy, ale stav si vždy můžete ověřit i GETem — webhook berte jako zrychlení, ne jediný zdroj pravdy.

Chyby a limity

  • 401 unauthorized — chybný nebo deaktivovaný token.
  • 402 subscription_inactive — vypršelé předplatné.
  • 422 bank_connection_missing / webhook_url_invalid / validation_failed — v těle je důvod.
  • Rychlostní limit 120 požadavků za minutu na klíč; párování samotné určuje banka (dotaz 1× za 30 s).