Integrace platební brány Stripe do checkoutu (Projekt Aurora)

Z mluveného zadání strukturovaný brief připravený k předání.

Ukázka skutečného výstupu

Souhrn

Marek z týmu Platby nadiktoval zadání na napojení platební brány Stripe do checkoutu e-shopu Projekt Aurora. Cílem je nahradit současnou ruční fakturaci kartou online, s podporou Apple Pay a Google Pay. Deadline na produkční nasazení je 15. července, MVP na testovacím prostředí do konce června.

Podrobný zápis

Co se má postavit

Cílem je do stávajícího checkoutu Projektu Aurora přidat platbu kartou přes Stripe. Zákazník po vyplnění košíku zvolí způsob platby a zaplatí přímo na stránce, bez přesměrování na externí bránu. Marek zdůraznil, že platební formulář má být vložený přes Stripe Elements, aby zůstal v designu e-shopu.

Kromě klasické karty se mají podporovat Apple Pay a Google Pay, protože podle analytiky tvoří mobilní objednávky přes polovinu provozu. Platba v hotovosti a na fakturu zůstávají zachované jako alternativy, Stripe je jen třetí volba navíc.

Technické požadavky a pojistky

Klíčová je spolehlivost potvrzení platby. Stav objednávky se nesmí měnit na základě odpovědi z prohlížeče, ale výhradně přes Stripe webhook na backendu (událost payment_intent.succeeded). Marek explicitně varoval před stavem, kdy zákazník zaplatí, ale spojení spadne a objednávka zůstane viset jako nezaplacená.

Každé volání musí být idempotentní (opakované spuštění nezaloží druhou platbu) přes idempotency key. Webhooky se musí ověřovat podpisem, aby je nešlo podvrhnout. Pro případ výpadku Stripe je požadovaný fallback — checkout nesmí celý spadnout, jen se skryje karta a nabídnou se zbylé způsoby platby.

Úkoly

Vytvořit backendový endpoint pro založení PaymentIntent se Stripe (částka, měna, idempotency key). · řeší backend tým · termín do 27. června vysoká
Integrovat Stripe Elements do checkoutu frontendu (karta, Apple Pay, Google Pay) v designu e-shopu. · řeší frontend tým · termín do 30. června vysoká
Naimplementovat webhook handler pro payment_intent.succeeded a payment_intent.payment_failed s ověřením podpisu. · řeší backend tým · termín do 27. června vysoká
Doplnit fallback: při nedostupnosti Stripe skrýt platbu kartou a nabídnout hotovost a fakturu. · řeší frontend tým · termín do 3. července střední
Připravit testovací scénáře (úspěch, selhání karty, výpadek webhooku, duplicitní platba) na testovacím prostředí. · řeší Lucie (QA) · termín do 8. července střední

Rozhodnutí

Platební formulář se vloží přes Stripe Elements přímo do checkoutu, bez přesměrování na externí stránku. 💬 z přepisu: „"Chci to mít vevnitř, ve stejném designu, ne aby to člověka přehazovalo někam na cizí stránku."“
Potvrzení platby se řeší serverovým webhookem payment_intent.succeeded, ne klientskou odpovědí. 💬 z přepisu: „"Zdroj pravdy je webhook na backendu, tečka."“
Apple Pay a Google Pay jsou součástí prvního MVP, ne pozdější fáze. 💬 z přepisu: „"Apple Pay a Google Pay ber jako součást základu, ne jako bonus na potom."“

Klíčové vhledy

Stav objednávky řídí výhradně serverový webhook, ne odpověď z prohlížeče — chrání před ztrátou platby při spadlém spojení. 💬 z přepisu: „"Nikdy, opravdu nikdy nepotvrzujte objednávku podle toho, co se vrátí do prohlížeče. Jen podle webhooku na serveru."“
Mobilní objednávky tvoří přes 50 % provozu, proto jsou Apple Pay a Google Pay součástí MVP, ne až druhé fáze. 💬 z přepisu: „"Přes polovinu lidí nakupuje z mobilu, takže Apple Pay a Google Pay musí být hned, ne někdy potom."“
Při výpadku Stripe se nesmí rozbít celý checkout, jen se skryje platba kartou a zůstanou hotovost a faktura. 💬 z přepisu: „"Když Stripe nepojede, ať nespadne celá pokladna. Prostě se schová karta a lidi zaplatí jinak."“

Data

15. července Produkční nasazení Termín pro spuštění platební brány v ostrém provozu.
konec června MVP na testovacím prostředí Funkční integrace připravená k testování.
vysoká priorita Priorita úkolu Marek označil platby kartou jako blokující pro letní kampaň.
přes 50 % Podíl mobilních objednávek Důvod pro zařazení Apple Pay a Google Pay do MVP.

Nejasnosti a rizika

Není určeno, zda se má podporovat ukládání karty pro opakované platby (saved cards) nebo jen jednorázové platby.
Marek nezmínil konkrétní limit pro automatické vrácení peněz (refund) — je nutné doladit s týmem podpory.
Nepadlo, v jakých měnách se bude platit (jen CZK, nebo i EUR pro zahraniční zákazníky).

Zadání pro realizátora

Implementační brief — Integrace platební brány Stripe (Projekt Aurora)

Cíl

Přidat do stávajícího checkoutu e-shopu Projekt Aurora platbu kartou přes Stripe, včetně Apple Pay a Google Pay, jako třetí způsob platby vedle hotovosti a faktury.

Rozsah (scope)

Platební formulář vložený přes Stripe Elements přímo do checkoutu (žádné přesměrování na externí bránu).
Podpora platebních metod: karta, Apple Pay, Google Pay.
Serverové potvrzování plateb přes webhooky (zdroj pravdy = backend, ne prohlížeč).
Fallback při nedostupnosti Stripe (degradace bez pádu celého checkoutu).

Mimo rozsah (out of scope)

Ukládání karet pro opakované platby (saved cards) — zatím neřešíme, čeká na rozhodnutí.
Refundy přes UI administrace — pro MVP stačí refund přes Stripe Dashboard.

Funkční požadavky

Založení platby
- Backend endpoint vytvoří PaymentIntent (částka, měna, idempotency_key).
- Frontend si vyžádá client_secret a vykreslí Stripe Elements.
Potvrzení platby
- Stav objednávky mění výhradně webhook payment_intent.succeeded.
- Klientská odpověď slouží jen k zobrazení „děkujeme" obrazovky, nikdy k potvrzení objednávky.
Selhání platby
- Webhook payment_intent.payment_failed → objednávka zůstane ve stavu „čeká na platbu", zákazník dostane možnost zkusit znovu.
Fallback
- Při nedostupnosti Stripe se skryje platba kartou a zobrazí se hotovost + faktura. Checkout nesmí spadnout celý.

Nefunkční požadavky

Idempotence: každé volání PaymentIntent použije idempotency key (opakované odeslání nezaloží druhou platbu).
Bezpečnost webhooků: ověření podpisu (Stripe-Signature), odmítnutí neověřených requestů.
Secrets: Stripe API klíče výhradně v GCP Secret Manageru, nikdy v kódu ani v .env v gitu.
Logování: každé selhání platby a každý příchozí webhook do structured logging (Cloud Logging).

Akceptační kritéria

Zákazník zaplatí kartou a objednávka se označí jako zaplacená až po přijetí webhooku payment_intent.succeeded.
Apple Pay a Google Pay se zobrazí na podporovaných zařízeních a fungují end-to-end.
Při vypnutém spojení po zaplacení (zavřený prohlížeč) je objednávka přesto označena jako zaplacená díky webhooku.
Dvojí odeslání platby nezaloží dvě platby (ověřeno idempotency key).
Podvržený webhook bez platného podpisu je odmítnut (HTTP 400).
Při simulovaném výpadku Stripe se checkout nerozbije, jen zmizí platba kartou.

Termíny

MVP na testu: konec června
Produkce: 15. července

Otevřené otázky

Ukládání karet pro opakované platby — ano/ne?
Měny: jen CZK, nebo i EUR?
Limit pro automatický refund?

Ukázka přepisu

Marek (zadavatel)

Tak jdeme na platby. Chci, abychom do checkoutu na Aurora konečně dostali platbu kartou přes Stripe. Teď to lidi platí buď hotově při převzetí, nebo na fakturu, a to nás brzdí.

Marek (zadavatel)

Důležité je, ať to zůstane vevnitř, ve stejném designu. Žádné přehazování na cizí stránku. Vložíme to přes ty jejich Elements, ať to vypadá jako součást e-shopu.

Marek (zadavatel)

A teď to nejdůležitější. Nikdy, opravdu nikdy nepotvrzujte objednávku podle toho, co se vrátí do prohlížeče. Jen podle webhooku na serveru. Už jsme jednou měli, že člověk zaplatil, spadlo mu spojení a objednávka visela jako nezaplacená. To se nesmí opakovat.

Marek (zadavatel)

Apple Pay a Google Pay ber jako součást základu, ne jako bonus na potom. Přes polovinu lidí nakupuje z mobilu, takže to musí být hned.

Marek (zadavatel)

A ještě jedna věc. Když Stripe nepojede, ať nespadne celá pokladna. Prostě se schová karta a lidi zaplatí jinak. Nechci kvůli výpadku brány přijít o celý prodej.

Marek (zadavatel)

Cílově to chci v ostrém do patnáctého července, kvůli letní kampani. Na testu ať to funguje do konce června, ať to Lucka stihne pořádně proklikat.

Vyzkoušet Voxibly