API pro e-shopy

Stejný párovací motor jako v pokladně, 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

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í, protože historie plateb na ně odkazuje.

API je součástí tarifu Standard i tarifu API. Bez předplatného je zdarma do 30 zaplacených plateb v kalendářním měsíci: počítají se zaplacené, ne vystavené, takže opuštěný košík nic nestojí. Od další zaplacené platby v témže měsíci vrátí vystavení chybu 402 free_tier_exhausted (níže) a prvního dne dalšího měsíce se pásmo obnoví. Klíče jdou vytvořit i bez tarifu (odkaz je na stránce Předplatné).

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",
  "return_url": "https://vas-eshop.cz/objednavka/123/dekujeme",
  "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, spayd (řetězec QR Platby, ze kterého vykreslíte QR kód) a payment_url (viz níže). Stav zjistíte kdykoli přes GET /api/v1/payment_requests/<id> (spayd vrací, jen dokud má smysl platit). U zaplacené platby je v odpovědi i notification_confirmed_at, connector_confirmed_at a final: kdo a kdy zaplacení potvrdil a jestli už je potvrzení konečné (kapitola Konektory).

Hostovaná platební stránka

Nejjednodušší integrace: QR nekreslete vůbec a zákazníka přesměrujte na payment_url z odpovědi. Je to naše veřejná stránka /p/<token> s částkou, jménem vašeho obchodu, QR kódem a živým stavem; na mobilu jde QR podržet nebo tlačítkem pod ním předat přes sdílení své bankovní aplikaci; platbu zákazník potvrdí v ní. Po zaplacení se ukáže ZAPLACENO, odkaz na doklad a tlačítko Zpět do obchodu, které vede na vaše return_url (nepovinné, absolutní https adresa). Zaplacení vám oznámí webhook jako obvykle; návrat zákazníka na return_url berte jen jako pohodlí, ne jako potvrzení platby. Vyzkoušet si to můžete v demu.

Jak se dozvíte, že zákazník zaplatil

Peníze jdou přímo na váš účet a párování děláme my; vy potřebujete jen zprávu „objednávka X je zaplacená“, abyste ji ve svém e-shopu označili jako uhrazenou a poslali zboží. Máte tři možnosti; první je ta správná:

Webhook (doporučeno). Při vystavení platby pošlete webhook_url. Jakmile se stav změní (paid, partially_paid, expired) a potvrzení je konečné (u provozovny s konektorem tedy po oznámení banky, nebo hned po konektoru, když to má správce zapnuté), pošleme na tuhle adresu POST s JSON tělem se stejnými údaji jako v odpovědi API, tj. id, reference (vaše číslo objednávky), status, received_amount, overpaid_amount (přeplatek zákazníka, který mu vracíte; u plateb přes API se nikdy nepočítá jako spropitné)… Váš server podle reference najde objednávku a při status: "paid" ji označí zaplacenou. Nedoručený webhook opakujeme s rostoucími odstupy; stejný webhook může přijít i dvakrát; zpracujte ho idempotentně (podle id).
Dotaz na stav. Kdykoli GET /api/v1/payment_requests/<id>; hodí se jako pojistka, když webhook nedorazil, nebo když e-shop nemá veřejnou adresu.
Návrat zákazníka na return_url potvrzením NENÍ. Zákazník se může vrátit i bez zaplacení (nebo se nevrátit vůbec); stav berte vždy jen z webhooku nebo z API.

Ověření webhooku

Aby vám nikdo nemohl podvrhnout „zaplaceno“, každý webhook podepisujeme hlavičkou X-Jenqr-Signature vaším webhook secretem (najdete ho u API klíče). Hlavička nese čas odeslání a podpis:

X-Jenqr-Signature: t=1755680000,v1=9f86d081...

Podepisuje se řetězec "<t>.<tělo požadavku>", tedy hodnota t z hlavičky, tečka a přesné tělo požadavku. Na své straně spočítejte totéž svým webhook secretem (HMAC-SHA256) a porovnejte s hodnotou v1. Nesedí-li podpis, webhook zahoďte.

Pokud chcete, můžete se navíc podívat na čas v t a hodně staré zprávy ignorovat; obvykle se volí okno v řádu minut. Zpravidla se to dělá proto, že samotný podpis neříká, kdy zpráva vznikla: kdyby se někomu dostal do rukou už doručený webhook, třeba z logu serveru, mohl by ho poslat znovu i za rok a podpis by pořád seděl. Každý pokus o doručení podepisujeme čerstvým časem, takže opakované doručení po výpadku vám kontrolou stáří nepropadne.

Tělo webhooku; přesně tenhle text se podepisuje, jen se před něj přidá t z hlavičky a tečka:

{
  "event": "payment_request.paid",
  "data": { "id": 123, "reference": "objednavka-123", "status": "paid",
            "amount": 250.0, "received_amount": 250.0, "tip_amount": 0.0,
            "overpaid_amount": 0.0, ... }
}

Chyby a limity

401 unauthorized: chybný nebo deaktivovaný token.
402 free_tier_exhausted: provozovna nemá předplatné a v tomto kalendářním měsíci už má 30 zaplacených plateb z API (bezplatné pásmo). V těle je limit, used a resets_on (první den dalšího měsíce). Stav dřív vystavené platby (GET /api/v1/payment_requests/:id) jde číst dál a konektor k ní hlásí dál; vystavovat znovu půjde s tarifem API nebo Standard (kapitola Předplatné).
403 workspace_unverified: provozovna ještě neprošla ověřením (kapitola První kroky).
422 bank_connection_missing / webhook_url_invalid / return_url_invalid / validation_failed: v těle je důvod.
403 connector_key_required: seznam otevřených plateb (GET /api/v1/payment_requests) a hlášení zaplacení (PATCH) jsou jen pro klíč konektoru (kapitola Konektory); klíč e-shopu potvrzovat nemůže.
Rychlostní limit 120 požadavků za minutu na klíč; rychlost párování určuje banka (oznámení o platbě chodí zpravidla do 15 s od jejího odeslání).