Rozsah reference a důvěrnost
EXCOIN dokončil implementaci platební brány a její rozšíření o kryptoměnové platby. Jméno klienta, datum, obchodní objemy, konkrétní procesory, podporované sítě a smluvní podmínky nejsou veřejné. Následující rozbor popisuje způsob, jak k takové dodávce přistupovat, a příklady rozhodnutí, která lze zveřejnit bez odhalení klientské implementace. Z jednotlivých návrhových vzorů nelze odvozovat přesný produkční stack této zakázky.
Předmětem není jen další tlačítko v pokladně. Platební tok propojuje objednávku, autorizaci, přijetí prostředků, potvrzení výsledku, vratku, účetní podklad a podporu zákazníka. Kryptoměnová větev přidává síť, aktivum, adresu, transakci, potvrzení na řetězci a možnou směnu do měny vypořádání. Každá z těchto událostí může přijít pozdě, dvakrát nebo v jiném pořadí. Architektura proto musí stát na jasném stavu a prokazatelné historii změn.
Od obchodního požadavku ke smlouvě rozhraní
První krok odděluje potřebu obchodníka, plátce a provozovatele. Obchodník potřebuje vytvořit platební záměr, zobrazit dostupné metody, zjistit stav, vyřídit vrácení a přiřadit peníze k objednávce. Plátce potřebuje srozumitelnou částku, měnu, časový limit a potvrzení. Provozovatel potřebuje audit, řešení výjimek, přehled nevyrovnaných částek a kontrolu přístupů. Takto vzniká inventář operací, nikoli seznam endpointů opsaný od jednoho poskytovatele.
Veřejné API má verzovaný kontrakt s přesnými měnovými jednotkami, identifikátorem obchodníka, idempotency key, korelačním ID, chybovým kódem a stavem, který lze bezpečně znovu přečíst. Zápis požadavku a jeho následné zpracování mají oddělené odpovědi. Pokud platební procesor neodpoví, nesmí systém předstírat zamítnutí ani potvrzení. Stav „výsledek neznámý“ spustí dohledání u zdroje; klientovi zůstává možnost opakovat dotaz bez vytvoření druhé platby.
Stavový model platby
Platební záměr, pokus o platbu, transakce poskytovatele, skutečné přijetí prostředků a obchodní objednávka jsou odlišné entity. Jedna objednávka může mít více neúspěšných pokusů, ale právě jeden účinný výsledek podle obchodního pravidla. Stavový automat výslovně popisuje vytvoření, čekání na akci plátce, zpracování, potvrzení, selhání, vypršení, vrácení a částečné vrácení. Přechody mají vlastníka a důkaz, například podepsanou událost poskytovatele či potvrzení z účetního systému.
Při zpožděném webhooku se stav nesmí vrátit z potvrzené platby do rozpracované. Duplicitní události se rozpoznávají podle identifikátoru poskytovatele a verze události. Konflikt mezi webhookem a aktivním dotazem se řeší pravidlem zdroje pravdy. Změna stavu objednávky se provádí odděleně; úspěšná platba sama o sobě ještě neprokazuje, že sklad, fakturace či doručení dokončily svou část procesu.
Karetní větev a odpovědnost za data
Při karetním toku je zásadní určit, kdo zachycuje a zpracovává číslo karty. Hostovaná platební stránka nebo komponenta poskytovatele může výrazně zúžit kontakt aplikace s kartovými údaji, ale neodstraňuje všechny povinnosti obchodníka. Rozsah PCI DSS závisí na skutečné architektuře a smluvním rozdělení odpovědností. Brána proto pracuje s tokenem či identifikátorem zpracovatele, neukládá citlivé autentizační údaje do aplikace a kontroluje načítané skripty platební stránky.
Autorizace, zachycení prostředků, zrušení autorizace, chargeback a refund jsou různé procesy s odlišným časováním. API a administrace nesmějí zobrazovat jeden univerzální stav „zaplaceno“, který tyto rozdíly smaže. Podpora potřebuje vidět cestu transakce a důvod zamítnutí ve vhodně omezeném rozsahu; zaměstnanec nemá získat plný přístup ke kartě nebo internímu tokenu jen proto, že řeší reklamaci.
Kryptoměnová větev: volba modelu
Před přidáním kryptoměny se volí model: zprostředkovaný poskytovatelem, nebo přímé přijímání do peněženky pod kontrolou provozovatele. První může přenést část infrastruktury a vypořádání na partnera; druhý vyžaduje správu klíčů, adres, sledování sítě, nakládání s prostředky a další provozní i regulatorní odpovědnost. „Podporujeme kryptoměny“ bez uvedení tohoto rozdílu nic nevysvětluje. Každou podporovanou kombinaci aktiva a sítě je třeba schválit samostatně.
Plátce musí dostat jednoznačnou částku, síť, aktivum, adresu nebo bezpečné propojení peněženky a dobu platnosti nabídky. Záměna tokenu, řetězce či memo/tag pole může znamenat ztrátu nebo nákladnou ruční nápravu. Brána nepovažuje samotné odeslání z peněženky za zaplacení. Rozlišuje detekci transakce, požadované potvrzení, finální přijetí poskytovatelem a účetní vypořádání. Počet potvrzení a pravidla finality jsou rozhodnutím pro konkrétní síť a aktivum.
Kurz, expirace a odchylky částky
Když je objednávka v korunách nebo eurech a plátce hradí digitálním aktivem, vzniká cenová nabídka. Ta má okamžik vydání, kurz, poplatky, dobu platnosti a pravidlo pro výkyv ceny. Změna kurzu mezi vytvořením objednávky a potvrzením na řetězci nesmí být skrytým doplatkem. Stejně důležité je rozhodnout, zda obchodník přijímá aktivum, stablecoin, nebo pouze fiat výnos z konverze; odpověď mění účetní i provozní postup.
Podplatba, přeplatek, platba po expiraci a druhá platba na stejnou adresu nejsou jen okrajové případy. Každá má předem určený stav, viditelný záznam a postup podpory. Automatická vratka není vždy bezpečná: odesílací adresa nemusí patřit plátci a vracení na jinou síť může být nemožné. Návrh proto odděluje automatické uzavření bezrozporného případu od ručně schvalované výjimky.
Webhooky, události a idempotence
Poskytovatelé posílají události asynchronně a mohou je opakovat. Příjem ověří podpis nebo jiný autentizační mechanismus, časové okno a identifikátor události; teprve potom ji uloží do trvalé fronty. Rychlá odpověď HTTP neznamená, že obchodní proces již doběhl. Worker zpracovává událost opakovatelně, mění stav atomicky a po výpadku pokračuje bez druhého účtování. Zpráva bez ověřeného původu nesmí vyvolat změnu stavu platby.
Idempotence platí na obou stranách hranice. Klientské opakování požadavku má vrátit tentýž platební záměr; opakované volání procesoru nesmí vytvořit druhé zachycení prostředků. Klíč je svázán s obchodníkem, operací, částkou a časovým oknem. Nelze jej bez pravidel recyklovat pro jiný nákup. V distribuovaném systému je nutné počítat i s tím, že odpověď zpracovatele dorazí po timeoutu klienta.
Účetní kniha a reconciliation
Záznam o platebním záměru není účetní kniha. Vnitřní ledger uchovává neměnné pohyby, měnu, čas, zdrojovou transakci, poplatek, refund, případně konverzi a vztah k obchodníkovi. Opravný zápis má nový důvod a schválení; původní stopa se nemaže. Celkové saldo se porovnává se zpracovatelem, bankou nebo blockchainovým zůstatkem podle konkrétního modelu. Tím se odhalí platba přijatá bez objednávky nebo objednávka označená za uhrazenou bez prostředků.
Reconciliation běží pravidelně a po incidentu. Rozlišuje časové rozdíly od skutečného nesouladu, drží seznam otevřených výjimek a přiřazuje odpovědnou osobu. Kryptoměnová transakce může být potvrzena na síti, zatímco poskytovatel teprve připravuje fiat vypořádání. Tyto dva stavy se nesmějí slít. Výkaz obchodníka má uvést referenci, částku, kurz, poplatek, čistý výnos a stav vypořádání s přiměřenou ochranou osobních údajů.
Refundace a reklamace napříč metodami
Karta a kryptoměna nemají stejný mechanismus vracení. Karetní refund se řídí možnostmi procesoru a může být částečný; u on-chain platby vzniká nová transakce, poplatek, rozhodnutí o cílové adrese a riziko chybné sítě. Brána musí podporu vést přes správnou větev. Plátci se má zobrazit očekávaná forma vrácení ještě před schválením procesu, nikoli až po jeho neúspěchu.
Každá vratka má vazbu na původní platbu, maximální zbývající částku, důvod, schvalovatele a důkaz provedení. Dvojí kliknutí v administraci nesmí vyvolat dvě vratky. Při selhání odeslání se nejprve zjišťuje skutečný stav u poskytovatele nebo na řetězci; slepé opakování by mohlo odeslat prostředky znovu. Proces reklamace zahrnuje také komunikaci s obchodníkem a oddělení sporné částky od ostatního vypořádání.
Identita, rizika a právní hranice
Brána odděluje oprávnění plátce, obchodníka, podpory, finanční kontroly a technického provozu. Změna vypořádacího účtu, limitu, podporovaného aktiva nebo adresy vyžaduje silnější ověření než běžné čtení stavu. Rizikový model sleduje neobvyklé opakování, nesoulad objednávky a platby, změny účtu a zneužití refundace. Pravidla blokace a eskalace musí mít vysvětlitelný výsledek pro podporu, ale nesmějí odkrývat obranné prahy útočníkovi.
Kryptoměnové služby mohou spadat do odlišných regulatorních režimů podle toho, kdo drží aktiva, provádí směnu a poskytuje službu v dané zemi. V EU je relevantní MiCA, ale samotná zmínka o ní neurčuje klasifikaci konkrétního produktu. Právní tým klienta a licencovaný poskytovatel musí potvrdit role, povinnosti identifikace, monitorování transakcí a smluvní odpovědnosti před spuštěním každé nové metody. Technická studie není právním stanoviskem ani tvrzením o licenci EXCOIN.
Bezpečnost provozu a ochrana tajemství
API klíče, webhooková tajemství a případné podpisové klíče peněženek se drží mimo zdrojový kód. Přístup je omezený na službu a prostředí, rotovatelný a auditovaný. Administrativní operace používají vícefaktorové přihlášení, oddělení rolí a u citlivých změn druhé potvrzení. Ochrana proti replay útoku, rate limiting a validace částek se týkají i interních volání; hranice důvěry nekončí na veřejném API.
Pro kryptoměnovou větev je nutné zvlášť analyzovat model úschovy klíčů. Pokud klíče drží externí poskytovatel, smlouva a technická integrace určují odpovědnost a postup incidentu. Pokud jsou ve správě systému, potřebují oddělené podepisování, limity výběru, kontrolu adres, obnovu a plán při kompromitaci. Auditní log nepřenáší privátní klíče ani celé přístupové tokeny.
Testy, simulace a uvádění do provozu
Testovací matice zahrnuje úspěšné karetní a kryptoměnové platby, zamítnutí, timeout, duplicitní webhook, transakci se špatnou sítí, podplatbu, přeplatek, expiraci, refund a rozpad mezi potvrzením a vypořádáním. Sandbox poskytovatele je užitečný, ale nemusí přesně simulovat síťové finality, vypořádání nebo chování při incidentu. Přechod do produkce proto používá omezené částky, zvláštní obchodníka či segment a ručně kontrolovanou reconciliaci.
Před rozšířením na další metodu se ověřují metriky dokončení plateb, stáří čekajících stavů, počet výjimek, doba vypořádání a podíl ručních zásahů. Neuvádíme zde dosažené hodnoty klienta. Důležitější než efektní průměr je umět pro konkrétní platbu od objednávky po výpis vysvětlit každý přechod a zpracovat nejhorší výjimku bez ztráty peněz či auditní stopy.
Pokladna jako uživatelský proces
Pokladna musí vysvětlit, co plátce kupuje, v jaké měně, komu platí a kdy bude objednávka potvrzena. Při změně metody se nemá ztratit stav objednávky. Odkaz na hostovanou stránku musí být svázán s konkrétní objednávkou a expirací; návrat z prohlížeče není důkazem úhrady. Při přerušení může zákazník pokračovat pouze tehdy, pokud původní záměr zůstává platný.
U kryptoměn nestačí zobrazit QR kód. Plátce musí rozpoznat síť, aktivum, částku, poplatek sítě a čas platnosti nabídky. Rozhraní upozorní na riziko nesprávné sítě a po odeslání ukáže ověřitelný stav, ne animaci předstírající definitivní úspěch. Přístupnost, jazyk a mobilní použití jsou součástí akceptace; překlep v dlouhé adrese se omezuje kopírováním a kontrolou.
Routování metod a dostupnost
Dostupné platební metody závisejí na obchodníkovi, měně, zemi, typu zboží a smlouvě s poskytovatelem. Rozhodovací pravidlo je verzované a testovatelné; skrytí metody je vysvětlitelné. Pokud procesor nefunguje, brána může nabídnout jinou metodu jen při zachování stejné objednávky a jasném souhlasu plátce. Nesmí automaticky odeslat platbu přes jiný kanál se změněnými podmínkami.
Fallback mezi poskytovateli vyžaduje ochranu před dvojím zachycením. Před přepnutím se dohledá stav prvního pokusu a případné neznámo se vyřeší. V administraci musí být vidět, proč byl zvolen konkrétní route a který poskytovatel drží autoritativní stav. Služba nemusí být globálně aktivní ve všech zemích; dostupnost se odvozuje od skutečných oprávnění a produktu.
Přesnost částek a měnové jednotky
Částky se drží v nejmenší jednotce příslušné měny nebo v přesném desetinném typu s explicitní škálou. Koruny, eura, tokeny s různými decimals a síťové poplatky se nesmějí převádět přes běžný float. Kontrakt stanoví, kdy se zaokrouhluje a kdo nese rozdíl. Výpis obchodníka musí umožnit zpětně sestavit původní cenu, slevu, daňový údaj, kurz, poplatek a čisté vypořádání.
Nulová a záporná částka, extrémní počet desetinných míst, změna měny po vydání nabídky a refund převyšující přijaté prostředky jsou povinné hraniční testy. Uživatelská lokalizace nesmí změnit skutečné číslo; čárka a tečka v zobrazení nejsou zdrojem účetní hodnoty. Při jakémkoli nesouladu se platba pozastaví pro kontrolu místo tiché korekce.
Sledování blockchainu a reorganizace
Služba sledující řetězec drží checkpoint podle sítě a bloku, rozpoznává transakce určené konkrétnímu platebnímu záměru a ověřuje tokenovou smlouvu. Nezaměňuje nativní převod a tokenový event. Musí umět dohnat výpadek RPC i přepnout poskytovatele bez ztráty nebo duplicitního započtení. Jedna adresa sdílená více platbami komplikuje párování; návrh musí obsahovat jednoznačný klíč.
Reorganizace může změnit dříve pozorované bloky. Stav „viděno“ proto není totéž co „potvrzeno“. Projekt stanoví bezpečnou hloubku potvrzení a postup, když dříve zaznamenaná transakce zmizí. Po finálním přijetí se odchylka eskaluje jako incident, ne jen přepíše záznam. Indexer, procesor i účetní vrstva musí sdílet korelační identifikátor.
Adresy, klíče a treasury
Přijímací adresa vzniká podle zvoleného modelu úschovy. Její přiřazení k objednávce se nesmí změnit bez auditní události. Pokud systém vytváří peněženky, odděluje online detekci plateb od možnosti podepisovat odchozí transakce. Výběrové limity, allowlist adres a případné schvalování dvěma osobami chrání prostředky. Klíče se nikdy nesmějí dostat do logu, chybové zprávy ani analytiky.
Treasury proces určuje, kdy se prostředky přesouvají, směňují nebo zůstávají v původním aktivu. Každá dávka má vazbu na přijaté platby, poplatky a výsledek. Přesun v rámci vlastních peněženek není nová zákaznická platba a nesmí ji zdvojit v ledgeru. Zůstatky se kontrolují po sítích a aktivech, protože stejné označení tokenu na různých řetězcích není jedna účetní položka.
Payout obchodníkovi
Přijetí od plátce a vyplacení obchodníkovi jsou dvě oddělené finanční operace. Payout se spouští až při splnění podmínek vypořádání, po odečtení poplatků, refundů a případných rezerv. Administrace zobrazuje plánované, odeslané, potvrzené a chybové výplaty. Změna bankovního účtu nebo cílové peněženky vyžaduje silné ověření, historii a čas na zachycení podvodu.
Při selhání výplaty se nejprve ověří stav u banky, procesoru nebo na řetězci. Opakování se řídí idempotencí a zůstatkem, nikoli manuálním dvojklikem. Obchodník dostane přehled položek, které dávku tvoří, a důvod případného zadržení. Vnitřní ledger umožní vyčíslit závazek vůči obchodníkovi nezávisle na technickém stavu odesílacího workeru.
Fraud a rozlišení rizika od chyby
Rizikový signál není totéž co technická chyba. Opakované karty, rychlé změny adresy, vysoký počet refundů nebo neobvyklý vzorec tokenových vkladů mohou vyžadovat kontrolu. Automatické rozhodnutí musí mít vstupy, verzi pravidla a možnost revize oprávněnou osobou. Plátce může dostat neutrální vysvětlení bez odhalení detekčních prahů. Technické chyby se nesmějí skrývat jako podezření z podvodu.
Ve větvi digitálních aktiv se posuzuje také zdroj prostředků a typ služby podle právního rámce klienta. Technický systém může poskytnout důkazy a workflow, ale neurčuje sám právní povinnost ani verdikt o osobě. Přehled otevřených případů musí mít vlastníka a lhůtu, aby se peníze nezadržovaly kvůli zapomenutému alertu.
Zákaznická podpora a vysvětlitelnost
Podpora musí z jednoho ID dohledat objednávku, platební záměr, pokusy, provider události, on-chain hash, refund a payout. Zobrazení používá maskované údaje a roli zaměstnance. Pro zákazníka je důležitá jasná odpověď, zda platba čeká na síť, je odmítnutá, přijatá nebo se řeší výjimka. U neznámého výsledku se nesmí slíbit konkrétní termín bez podkladu.
Každý ruční zásah se zapisuje s důvodem a vazbou na důkaz. Není dovoleno přepsat stav na „úspěch“ jen proto, že zákazník poslal snímek obrazovky peněženky. Snímek lze připojit k případu, ale skutečné přijetí ověřuje autoritativní procesor či řetězec. Audit slouží i k vysvětlení reklamace po několika měsících.
Incidentní scénáře a degradace
Runbooky oddělují výpadek checkoutu, procesoru, webhooků, RPC, směnné služby a účetní databáze. Pro každý případ stanoví, zda lze bezpečně přijímat nové záměry, zobrazovat čekající platby a provádět refundy. Když není možné potvrdit platbu, brána nesmí vydávat objednávky jako uhrazené. Při obnově se projdou nevyřízené záměry a znovu srovnají stavy u zdrojů.
Záložní poskytovatel není záruka bezvýpadkovosti. Může mít jiný stavový model, limity či právní rozsah. Přepnutí se nacvičuje na konkrétní metodě a měně, včetně rozpracovaných plateb. Incidentní zpráva zaznamenává dopad, časovou osu, rozhodnutí o refundu a výsledek reconciliace; samotný zelený healthcheck není uzavření finančního incidentu.
Ochrana osobních údajů a retence
Platební data mohou obsahovat identitu plátce, IP adresu, fakturační údaje a citlivé poznámky podpory. Každé pole má účel, přístupovou roli a dobu uchování podle skutečných smluvních a právních povinností. Vývojové logy a analytika nemají kopírovat celý obsah webhooků. Při předání dat poskytovateli musí být jasné, kdo je správcem či zpracovatelem a v jakém regionu data zůstávají.
Požadavek na výmaz se řeší s vědomím, že některé účetní a blockchainové záznamy nelze technicky odstranit. Návrh omezuje osobní informace v on-chain datech a odděluje jejich identitu od veřejného hashe. Retenční proces maže dočasné exporty a diagnostické payloady, aniž by porušil povinnou finanční stopu. Pravidla potvrzuje právní tým klienta.
Migrace staré brány
Při rozšíření existující brány se nejprve mapují staré stavy, identifikátory a otevřené refundy. Nové kryptoměnové metody nesmějí změnit význam staré karetní historie. Adaptační vrstva může obsluhovat staré i nové pokusy, ale každá událost musí ukazovat verzi schématu. Přepnutí obchodníků probíhá po segmentech a obsahuje návratovou cestu pro dosud nevypořádané platby.
Migrace se nevyhodnocuje pouze podle počtu nových transakcí. Důležitá je shoda ledgeru se starým procesorem, přístupnost historických dokladů a schopnost podpory vyřešit reklamaci z doby před změnou. Kontrolní součty a vzorky se archivují jako důkaz. Pokud stará data chybí, nové rozhraní musí mezeru přiznat.
Verzování, kontrakty a rozšíření partnerů
Když se přidá další poskytovatel, vnější API zůstává stabilní jen tehdy, pokud zůstává stabilní význam stavů. Nová metoda může potřebovat zvláštní pole pro síť, memo, expiraci nebo potvrzení; tato pole se nesmějí schovat do neurčitého JSON bez validace. Kontraktové testy chrání staré obchodníky před změnou, která by jim přepsala statusy nebo vytvořila duplicitní objednávku.
Každý partner má vlastní katalog chyb, webhooků, limitů, storna a vypořádání. Adaptér jej převádí na doménové události, ale zachovává originální důkaz v omezeném úložišti. Po ukončení partnera se musí dopracovat rozpracované platby, refundy a historické dotazy. Odstranit konfiguraci není totéž co uzavřít finanční závazky.
Provozní servis a další rozšiřování
Po nasazení je potřeba vlastník incidentů, kontakty na poskytovatele, postup při nedostupnosti procesoru nebo sítě, práce s frontou, denní reconciliation a plán obnovy. Dashboard sleduje zvlášť dostupnost API, úspěšnost metod, backlog webhooků, nevyrovnané platby a výplaty. Alert musí vést ke konkrétnímu postupu a odpovědné roli. Stavové údaje do veřejné pokladny přicházejí z autoritativního záznamu, ne z náhodného posledního callbacku.
Nové aktivum, síť či procesor se přidávají přes stejný kontrakt a akceptační matici: měna, přesnost, finální potvrzení, poplatky, refund, právní role, testovací scénáře a provozní vlastník. Rozšíření nelze vyhodnotit jen podle toho, zda transakce prošla. Musí se ověřit i fakturace, účetnictví, podpora, monitoring a odpojení nové metody bez narušení již přijatých plateb.
Obecné technické podklady
Tyto odkazy vysvětlují obecné principy. Nedokládají konkrétní neveřejnou implementaci klienta.