Platební API: připravte integraci i nejasné výsledky

Modelujte objednávku a pokus samostatně

Objednávka stanoví prodávané plnění a platební pokus má vlastní technický průběh. Dejte oběma stabilní reference a uchovejte jejich spojení. Nejasný stav objednávky nemá sám vytvořit další pokus. Určete také účet, obchod a prostředí používané požadavkem. U více obchodů musí volba vycházet z důvěryhodných serverových údajů, nikoli jen z hodnoty upravitelné v prohlížeči. Výslovný model pomůže zpětně vysvětlit použitou konfiguraci. Zároveň umožní předávat případ mezi týmy bez zjednodušení na částku, která se může v mnoha různých transakcích opakovat.

Integrace a API

Dodržte formát částky z dokumentace

Každé API určuje způsob zápisu hodnoty. Použijte přesně tuto konvenci a nepřenášejte automaticky formát z jiné integrace. OrsunPay dokumentuje částky jako desetinné řetězce. Před voláním ověřte měnu a konečnou verzi objednávky. Slevy a změny musí být promítnuty už před vytvořením požadavku. Projděte příklad od obchodních dat po výsledek a ukažte místo validace. Správně vypadající checkout nevylučuje chybu převodu, pokud systémy rozdílně interpretují čísla. Zapsaná pravidla usnadní i kontrolu kódu a pozdější hledání příčiny nesrovnalostí po spuštění.

Hostovaná platební stránka

Připravte ztracenou odpověď bez slepého opakování

Server může požadavek zpracovat, přestože odpověď aplikaci nedojde. V tu chvíli ještě není jasné, zda transakce existuje. Další vytvoření bez ověření může způsobit duplicitu. Použijte dokumentovanou idempotenci a zachovejte vztah klíče k obchodnímu požadavku. Oddělte opakování stejného volání od vědomé nové platební operace. Nenechte každého klienta API vytvořit vlastní strategii pro časový limit. Společné pravidlo omezí souběžné, rozporné pokusy o nápravu a určí, který proces má odpovědnost za zjištění neznámého výsledku. Toto chování patří do návrhu, ne až do improvizace při incidentu.

Ověřte webhook před změnou objednávky

Veřejný endpoint nemá důvěřovat zprávě jen proto, že má očekávanou strukturu. Před obchodní akcí zkontrolujte podpis. OrsunPay popisuje HMAC-SHA256 nad nezměněnými surovými bajty těla. Přestavění nebo formátování dat před ověřením může výsledek změnit. Tajné klíče nepatří do prohlížeče a logy nemají zbytečně uchovávat citlivé informace. Dokumentace Stripe i Mollie zdůrazňují roli serverových událostí v platebním cyklu. Ověření původu a způsob evidence zprávy mají být součástí integrace od začátku, nikoli dodatečným opatřením po prvním neočekávaném požadavku.

Proveďte obchodní účinek pouze jednou

Po technické kontrole aplikace rozhodne, který přechod stavu je povolený. Stejná informace o úspěchu nesmí vyvolat dvě zásilky nebo aktivace. Evidujte zpracování tak, aby byl duplikát rozpoznatelný bez opakování účinku. Počítejte i s pozdními událostmi. Návratová stránka může zákazníka informovat, ale sama není platební důkaz. Rozhodnutí o plnění má vycházet z ověřeného serverového výsledku a pravidel objednávky. Proces tak zůstane správný i tehdy, když zákazník vůbec neotevře návratovou stránku a nedodá žádný obrázek potvrzující, co v prohlížeči viděl.

Připravte provozní předání podpoře

Podpora potřebuje vyhledatelnou referenci a srozumitelný důvod otevřeného případu. Popište, kdy lze opakovat interní zpracování a kdy kontaktovat PSP. OrsunPay propojuje vlastní účty, nenahrazuje jejich podmínky ani schvalovací rozhodnutí. Před zahrnutím potřebného SDK nebo balíčku do termínu potvrďte jeho publikaci. Kód v repozitáři není důkazem veřejně dostupné distribuce. Předání je užitečné, když další pracovník dokáže s dostupnými údaji prověřit vzorový incident a vysvětlit zákazníkovi známou fázi bez hádání. Technická dokumentace a obchodní reference mají podporovat stejné rozhodnutí.

• Simulujte ztrátu odpovědi po vytvoření operace.
• Zkontrolujte neplatný podpis a opakované oznámení.
• Sledujte částku, měnu a kontext obchodu.
• Zapište postup pro neznámý výsledek.
• Používejte společné reference ve vývoji i podpoře.

Zdroje

• Dokumentace Stripe k webhookům
• Dokumentace Mollie k platbám