Nejdřív popište celý životní cyklus platby
Slovo „zaplaceno“ může znamenat různé věci podle produktu a poskytovatele. Požadavek může být vytvořen, autorizován, potvrzen, zpracováván, vypořádán, vrácen nebo napaden. Tyto stavy nejsou pouhými barvami v uživatelském rozhraní: ovlivňují vydání služby, účetní evidenci, podporu a komunikaci s klientem. Před návrhem je proto nutné přesně určit, který stav opravňuje jakou obchodní akci a kdo jej potvrzuje.
Mapa toku má zahrnout zákazníka, interní aplikaci, poskytovatele plateb, případný bankovní systém a proces řešení sporů. Zapisují se identifikátory, časové značky, měny, částky, důvody změny stavu a odpovědnost za opravu. U každé hranice se ptáme, co se stane, když druhá strana neodpoví. Pokud se systém chová dobře jen při okamžitém úspěchu, není platební tok dokončený ani tehdy, když všechny obrazovky vypadají hotově.
Neznámý výsledek není zamítnutí
Při timeoutu aplikace často neví, zda poskytovatel operaci provedl. Automatické opakování bez souvislostí může vytvořit duplicitní platbu; automatické označení za neúspěch může zákazníka vyzvat k další platbě, která není potřeba. Proto se používá stabilní identifikátor obchodní operace, stav čekající na ověření a cesta k získání skutečného výsledku. Uživatelské sdělení má odpovídat míře jistoty, kterou systém opravdu má.
Idempotentní požadavek pomáhá bezpečně opakovat technické volání. Jeho přesné chování však závisí na konkrétním API, době uchování klíče a parametrech žádosti. Dokumentace Stripe například popisuje práci s idempotency key a rozdíly mezi verzemi API. Tuto vlastnost nelze přenést automaticky na každého poskytovatele. Před implementací je třeba ověřit, jak partner identifikuje opakování, co vrací po chybě a jak se chová při souběžných žádostech.
Události a webhooky jako zdroj změn
Asynchronní událost může potvrdit stav až po návratu uživatele ze stránky poskytovatele. Webhook proto často patří mezi důležité vstupy platebního procesu. Je nutné ověřit jeho původ, zpracovat událost vícekrát bezpečně a oddělit přijetí zprávy od dokončení navazující práce. Někteří poskytovatelé nezaručují doručení v pořadí, jaké by si aplikace přála. Stav se proto nemá odvozovat pouze z poslední přijaté zprávy bez kontroly jejího významu.
Oficiální dokumentace Stripe popisuje podepisování webhooků a potřebu pracovat s původním tělem požadavku při ověření podpisu. Jiný poskytovatel může mít odlišný mechanismus. Dobré řešení ukládá identifikátor události, zaznamenává důvod odmítnutí chybné zprávy a umožňuje bezpečné opakované zpracování. Těžkou práci lze přesunout za rychlé potvrzení přijetí, pokud je zajištěno její trvalé a pozorovatelné dokončení. Samotný HTTP kód 200 ještě nedokazuje, že účetní stav souhlasí.
Párování a oprava rozdílů
Interní evidence a poskytovatel se mohou dočasně lišit. Příčinou bývá opožděná událost, ruční zásah, ztracená zpráva, vrácení platby nebo změna u jiné strany. Integrace potřebuje pravidelné párování podle stabilních identifikátorů, částky, měny a očekávaného stavu. Výsledek párování nemá být pouze číslo na dashboardu; musí vytvořit řešitelný případ s vlastníkem a podklady. Při ruční opravě je důležité zachovat původní historii.
Není bezpečné automaticky přepsat jeden systém podle druhého bez pravidel, která určují autoritu pro konkrétní údaj. Jiný zdroj může být rozhodující pro autorizaci, jiný pro vypořádání a další pro zákaznickou fakturu. Tato pravidla se stanovují při návrhu a testují na příkladech včetně částečných refundací. První provozní verze má obsahovat postup, jak rozdíl odhalit a uzavřít, ne jen předpoklad, že k němu nedojde.
Ochrana dat a rozsah odpovědnosti
Platební údaje mají vysokou citlivost a jejich tok je třeba minimalizovat. Je rozdíl mezi aplikací, která ukládá karetní údaje, a aplikací, jež pouze předává zákazníka hostované platební službě. Skutečný rozsah odpovědnosti se však určuje podle celé architektury a smluv, nikoli jen podle jedné obrazovky. PCI Security Standards Council popisuje PCI DSS jako rámec pro ochranu platebních účtů u subjektů, které ukládají, zpracovávají nebo přenášejí příslušná data či ovlivňují jejich prostředí.
Konkrétní povinnosti musí posoudit kvalifikované osoby podle produktu a poskytovatele. Technické rozhodnutí může zmenšit rozsah zpracovávaných citlivých dat, ale samo neprokazuje shodu. Tajemství pro API a webhooky se ukládají mimo kód, mají omezený přístup a plán rotace. Logy, analytika a chybové zprávy nesmějí zbytečně obsahovat osobní nebo platební údaje. Role pro refundaci nebo změnu nastavení mají být odděleny od běžného čtení stavu.
Testy, které mají skutečnou hodnotu
Úspěšná platba v testovacím prostředí je pouze začátek. Sada scénářů má obsahovat timeout po odeslání, opakované kliknutí, duplicitní webhook, události v jiném pořadí, odmítnutí, zrušení, refundaci, neznámý výsledek a výpadek vlastní databáze. U každého scénáře se kontroluje zákaznické sdělení, interní stav, účetní vazba a možnost opravy. Testy používají simulované údaje; produkční tajemství ani skutečné platební údaje nepatří do vývojových ukázek.
Vedle automatických testů je užitečné provést provozní cvičení: vypnout zpracování událostí, nechat několik zpráv čekat a sledovat, zda se po obnově bezpečně doženou. Měřte počet neuzavřených plateb, stáří nejstarší události, rozdíly v párování a čas do vyřešení výjimky. Alarm musí být navázán na člověka a postup. Pokud systém umí hlásit problém, ale nikdo neví, jak jej napravit, provozní riziko zůstává.
První dodávka a hranice integrace
První ucelený tok má přijmout záměr platit, vytvořit operaci s vlastním identifikátorem, předat ji poskytovateli, přijmout potvrzení, bezpečně zpracovat opakovanou událost a zobrazit pravdivý stav zákazníkovi. Součástí je také jedna cesta k ručnímu prověření neznámého výsledku. Tím se ověří hlavní kontrakt a model stavu. Další poskytovatelé, platební metody nebo komplexní refundace se přidávají podle skutečné potřeby, ne do první verze automaticky.
Před odhadem je třeba znát poskytovatele, dostupnost jeho testovacího prostředí, cílové trhy, měny, typ produktu, požadované metody a vlastníka účetní evidence. Důležité je určit, kdo může schválit refundaci a kdo komunikuje s klientem při nejasném výsledku. Když tyto odpovědi chybí, první etapou je technické a procesní discovery. Výstupem má být mapa stavů, datové kontrakty, testovací scénáře, návrh párování a plán provozu; teprve pak má smysl přesně vymezit implementaci.
Kontrolní otázky před spuštěním
Platební cesta musí být vysvětlitelná lidem mimo vývojový tým. Když zákazník oznámí problém, podpora potřebuje najít operaci a určit, co je známo, co se ověřuje a jaký je další krok. Provozní tým potřebuje identifikovat ztracenou událost nebo nesoulad a bezpečně je napravit. Vlastník produktu potřebuje rozumět riziku a schválit hranice automatizace. Pokud tyto tři pohledy chybí, samotný technicky funkční endpoint nestačí. Zvlášť užitečné je společně projít případ, kdy zákazník vidí úspěch, interní evidence čeká na událost a poskytovatel již peníze zpracoval. Teprve takový scénář ukáže, zda jsou stavové názvy, odpovědnost a opravný postup pro všechny srozumitelné i při výpadku.
- Je jasné, který stav opravňuje vydání služby nebo zboží?
- Má každá operace stabilní interní i partnerský identifikátor?
- Umí systém odlišit zamítnutí od zatím neznámého výsledku?
- Co se stane při opakovaném požadavku a duplicitní události?
- Jak se ověřuje původ webhooku a chrání jeho tajemství?
- Kdy a jak se párují interní a externí záznamy?
- Kdo může provést refundaci a kdo schvaluje výjimku?
- Prošel tým zkouškou obnovy se zprávami čekajícími na zpracování?