Nejdřív rozlište přijetí a dokončení
Platební tok může potvrdit několik různých věcí: že aplikace přijala záměr, poskytovatel přijal příkaz, platba byla autorizována, zpracována nebo definitivně vypořádána. Tyto okamžiky nelze sloučit do jediného stavu „úspěch“. Před implementací sepište stavový model podle skutečného poskytovatele a produktu. U každého stavu určete, co smí vidět klient a co už smí podniknout provozní systém. Potvrzení HTTP odpovědi není samo o sobě důkazem pohybu peněz. Pokud klientská obrazovka oznámí dokončení příliš brzy, následné zamítnutí se změní v problém podpory a důvěry.
K platbě přidělte stabilní interní identifikátor a uchovejte identifikátor poskytovatele. Potřebujete je k párování zpráv, ručnímu dohledání a rekonciliaci. Uveďte částku, měnu, případné poplatky a pravidla zaokrouhlení. Nedovolte, aby nový pokus se stejným obchodním záměrem potichu vytvořil druhou transakci. Rozhodnutí, kdy jde o nový nákup a kdy o opakování, patří procesu, ne jen implementaci HTTP klienta. Aplikace musí umět odpovědět, co o operaci ví a co zatím neví, aniž by z neznámého stavu automaticky udělala chybu.
Timeout vytváří neznámý výsledek
Představte si, že aplikace odešle příkaz a spojení se přeruší těsně před odpovědí. Poskytovatel mohl platbu vytvořit, ale volající o tom neví. Při automatickém opakování s novým identifikátorem vznikne druhá operace. Proto rozlišujte bezpečné opakování se stejným idempotentním klíčem, dotaz na stav a nové zadání. Stripe dokumentuje idempotentní požadavky jako způsob, jak bezpečně opakovat určité operace; konkrétní rozsah a životnost klíče vždy ověřte u daného API. Nemůžete předpokládat, že každá platební služba poskytuje stejnou záruku. Při chybě nejprve zjistěte, co protistrana skutečně provedla.
Neznámý stav zobrazte člověku srozumitelně. Klient nemusí vidět technický timeout, ale má vědět, že potvrzení čeká a neměl by zbytečně zadat další platbu. Operátor potřebuje interní ID, poslední potvrzený krok a bezpečný postup ověření. V přechodné době lze omezit další akce nad stejným případem, aby se stav ještě nezamotal. Nastavte časový limit, po kterém se spustí ruční šetření nebo automatická kontrola u poskytovatele. Nenechte čekající případ zmizet jen proto, že neodpověděl původní HTTP požadavek.
Idempotence musí přežít souběh a restart
Klíč pro opakování spojte s obchodní operací, nikoli s časem přijetí požadavku. Příjemce má evidovat, že daný příkaz zpracoval, v trvalém úložišti. Microsoftův vzor idempotentního příjemce popisuje opakované doručení a upozorňuje i na souběžné kopie zprávy. Pouhá kontrola záznamu před zápisem nemusí stačit, pokud dvě instance projdou kontrolou současně; rozhodující je bezpečný zápis s unikátním omezením. Klíč musí mít jasný rozsah a pravidlo uchování. Pokud se po čase recykluje, systém může starý opakovaný požadavek považovat za nový. Rozhodnutí proto musí odpovídat chování konkrétního poskytovatele.
Idempotence je potřebná i uvnitř vaší aplikace. Webhook může vyvolat aktualizaci objednávky, e-mail a účetní událost. Pokud každá část používá jiné ID a žádná si nepamatuje zpracování, jedna opakovaná zpráva může spustit více vedlejších účinků. U každého konzumenta proto stanovte, co smí udělat jednou a co se může bezpečně opakovat. V testu pošlete stejnou zprávu dvakrát současně a pak znovu po restartu. Výsledkem má být jeden správný obchodní účinek a dohledatelná informace, že duplicitní doručení bylo rozpoznáno.
Webhooky přicházejí podle reality sítě
Webhook není synchronní pokračování původního požadavku. Může dorazit opožděně, opakovaně nebo v jiném pořadí. Stripe ve své dokumentaci webhooků popisuje ověřování událostí a praktické zacházení s doručením; konkrétní pravidla se u jiných poskytovatelů liší. Ověřujte podpis nebo jiný mechanismus původu a omezte, co webhook smí změnit. Nejprve jej bezpečně přijměte a zaznamenejte identifikátor, potom zpracujte. Pokud odpověď vašeho endpointu selže po provedení vedlejšího účinku, poskytovatel může událost poslat znovu. Návrh musí tuto možnost přijmout bez druhé platby či druhého potvrzení.
Stavový automat má chránit před pozdní zprávou, která by přepsala novější konečný stav. Uchovejte původní události a rozhodněte, jaký přechod je platný. U některých poskytovatelů je bezpečnější po oznámení načíst aktuální stav objektu než věřit, že každá událost sama obsahuje úplný konečný obraz. Ověřte to v dokumentaci protistrany. Nezpracovatelný webhook odložte s důvodem a možností kontrolovaného opakování. Neztrácejte jej v logu, který se po několika dnech smaže. Podpora potřebuje vidět, zda zpráva čeká, selhala nebo již byla zpracována.
Rekonciliace opravuje to, co běžný tok nevidí
Ani dobře napsaný webhook nezaručí, že každý interní stav odpovídá záznamu u poskytovatele. Pravidelně porovnávejte interní platby se stavem protistrany, identifikátory, částkami, měnou a relevantním časovým obdobím. Nestačí porovnat součet tržeb: dvě chybné transakce se mohou v agregátu vyrušit. Definujte toleranci pro čekající stavy a okamžik, kdy se rozdíl stává výjimkou. Každá výjimka má mít vlastníka, prioritu, poslední provedený krok a bezpečnou cestu opravy. Výsledek rekonciliace sledujte jako produktovou metriku, nikoli jako interní technický soubor.
Oprava může znamenat znovu načíst stav, přiřadit chybějící událost, vrátit peníze nebo vytvořit opačný účetní záznam. Nikdy nesmažte historii tak, že původní nesoulad nebude možné vysvětlit. Před zásahovou akcí se ujistěte, zda poskytovatel již něco neprovedl. U důležitých operací vyžadujte schválení druhým člověkem podle skutečného rizika. Reconciliation report má ukazovat otevřené rozdíly podle stáří a částky, ale nesmí automaticky zveřejňovat citlivé údaje každému správci. Měřte dobu uzavření výjimky a příčiny, které se opakují.
Testovací matice musí obsahovat nepříjemné kombinace
Před spuštěním vyzkoušejte úspěch, zamítnutí, timeout před odesláním i po něm, dvojí kliknutí, opakovaný požadavek, dva souběžné webhooky, ztracené potvrzení a výpadek databáze při zápisu stavu. U každého scénáře stanovte, co vidí klient, co je v interní evidenci, co tvrdí poskytovatel a jak se případ vyřeší. Testujte i obnovu po restartu. Pokud sandbox poskytovatele nedovolí konkrétní poruchu vytvořit, simulujte ji v integrační vrstvě. Úspěšná platba v testu neprokazuje, že aplikace zvládne neznámý výsledek nebo zdvojené oznámení.
Zvlášť prověřte hranice: stejný klíč s jinými parametry, expiraci klíče, pozdní refundaci a webhook o události, kterou interní systém nezná. Chybové zprávy mají vést k bezpečnému rozhodnutí. Pokud klient po timeoutu vidí tlačítko zaplatit znovu bez vysvětlení, test ukázal produktový problém. Neomezujte se na kód; nechte operátora projít případ podle provozního návodu. Potřebuje najít identifikátory, porovnat stav a vybrat opravu bez hádání. Nalezenou mezeru přidejte do regresních testů a dokumentace.
Odpovědnosti a limity určete před ostrým provozem
Platební poskytovatel, vaše aplikace a účetní systém mohou mít odlišné SLA a různý okamžik konečnosti. Sepište kontakty, provozní hodiny, eskalaci a pravidla komunikace s klientem. Rozlište technickou chybu od zamítnutí obchodním pravidlem. Předem stanovte, kdy je vhodné operaci zastavit, kdy pouze zpozdit potvrzení a kdo smí provést refundaci. Konkrétní regulatorní požadavky se liší podle produktu a jurisdikce; technický návrh je musí ověřit se specialistou. Neslibujte nulové výpadky ani absolutní absenci duplicit. Slibujte kontrolu, která je měřitelná a provozně použitelná.
EXCOIN může pomoci navrhnout a implementovat konkrétní platební tok, ale správné chování závisí na dokumentaci a smlouvě s protistranou. První etapa má dodat stavový model, datovou smlouvu, pravidla idempotence, scénáře poruch a rekonciliaci. Po pilotu měřte počet neznámých stavů, duplicitních doručení, ručních oprav a dobu vysvětlení sporného případu. Pokud systém umí při selhání bezpečně říci „zatím nevíme“ a poté výsledek zjistit, je to často důležitější než bezchybně vypadající ukázka jediné úspěšné platby.
Při závěrečném cvičení nechte člověka z podpory řešit záměrně nejasný případ bez asistence vývojáře. Měl by najít interní i externí identifikátor, ověřit poslední potvrzený stav, rozhodnout, zda je bezpečné operaci zopakovat, a zaznamenat své kroky. Pokud musí hádat, chybí buď evidence, nebo provozní návod. Výsledek cvičení převeďte na konkrétní úkoly před spuštěním. Opakujte jej po změně platebního poskytovatele nebo významné úpravě webhooku. Schopnost vysvětlit chybu klientovi a bezpečně ji napravit je nedílnou součástí kvality integrace, i když se obtížně ukazuje na běžné produktové prezentaci.