Architektura platební integrace: Karty, peněženky, faktury a stav objednávek

Integrace plateb málokdy spočívá v pouhém vložení jediného SDK. Při našich stavbách v DigiForge jsme viděli projekty, které nabobtnaly, protože týmy podcenily složitost zpracování více platebních metod – karet, digitálních peněženek, fakturovaných plateb – a jejich následného provázání s životním cyklem objednávky. Každý typ platby má svá specifika a jejich slepování bez soudržné architektury vede k křehkému kódu a bolestivému párování. Tento článek rozebírá, jak vypadá jednotná platební integrační vrstva, přičemž čerpá jak z osvědčených vzorů, tak z novějších trendů, jako jsou karty kryté stablecoiny.

Karty: Tokenizace, síťové tokeny a nástup karet krytých stablecoiny

Karetní platby zůstávají páteří e-commerce a mnoha SaaS firem. Zlatým pravidlem je nikdy nezacházet s holými čísly karet. Tokenizace prostřednictvím PCI kompatibilní brány (Stripe, Braintree, Adyen) je základ. Existuje však jemnější vrstva: síťové tokeny. Jde o zařízení specifické, jednorázové tokeny vydávané samotnými kartovými sítěmi, které nabízejí lepší míru autorizace a snižují podvody. Obvykle klienty tlačíme k přijetí síťové tokenizace brzy, zejména pokud zpracovávají opakované platby, protože životnost tokenů je delší a aktualizace řeší síť.

Novější vlnou jsou karty kryté stablecoiny. Ke konci roku 2025 dosáhl objem krypto karet anualizovaného tempa 18 miliard dolarů, přičemž od roku 2023 rostl o 106 % ročně (tisková zpráva Wirex/Crossmint). Architektura je zde odlišná: místo čerpání z bankovního účtu nebo úvěrového rámce karta čerpá z peněženky se stablecoiny. Pro vývojáře to znamená integraci s poskytovatelem peněženky (např. chytrá peněženka Crossmint) a vydavatelem karty (např. Wirex). Výzvou je compliance – tisková zpráva uvádí, že fintech firmy dříve musely skládat peněženku, vydavatele a compliance rámce samostatně. V DigiForge jsme pracovali na podobných multi-vendor integracích a zjistili jsme, že abstrakční vrstva s jednotným modelem transakcí je nezbytná. Jinak se ladění neúspěšné platby změní v hon za příčinou napříč třemi dashboardy poskytovatelů.

Digitální peněženky: UPI, Google Pay a integrace hostovaná vs. API řízená

Digitální peněženky nejsou monolitické. Google Pay (nyní součástí širšího ekosystému Google Payments) funguje jinak než indické peněženky založené na UPI, jako je Paytm, a obě se liší od peněženek specifických pro aplikace. Architektonické rozhodnutí spočívá v tom, zda použít hostovaný checkout (jednodušší, méně kontroly) nebo integraci řízenou API (složitější, bohatší uživatelský zážitek).

U peněženek jako Google Pay, Apple Pay a PayPal je běžným vzorem tlačítko peněženky, které spouští panel nebo přesměrování. Integrace se obvykle provádí prostřednictvím jednotného checkoutu platební brány – například Stripe Payment Element vykresluje všechny peněženky automaticky. To je pro mnoho případů dostačující, ale narazili jsme na omezení, když potřebujete vlastní stylování nebo chcete před platbou shromáždit další údaje. Hlubší integrace prostřednictvím vlastního SDK peněženky poskytuje větší kontrolu, ale zavazuje vás k údržbě samostatných kódových cest.

Peněženky založené na UPI, jako je Paytm, fungují odlišně. UPI (Unified Payments Interface) je okamžitý platební systém umožňující přímé převody mezi bankami. Při integraci Paytm jako platební metody je typický tok následující: uživatel vybere Paytm, backend vygeneruje platební požadavek, uživatel autorizuje v aplikaci Paytm a Paytm odešle zpětné volání. Výzvou je zde idempotence – platby UPI mohou na straně banky uspět, ale obchodníkovi nahlásit selhání kvůli časovému limitu sítě. Vždy vytváříme reconciliační úlohu, která každých pár minut porovnává náš stav objednávky se stavem transakce v Paytm.

Faktury: Platební požadavky a reconciliace

Fakturované platby – kdy firma vystaví účet a zákazník zaplatí později – přinášejí odlišnou sadu problémů. Stránka IRS Payments (irs.gov/payments) je příkladem rozsáhlého fakturačního systému: zjistíte svůj zůstatek (přes oznámení nebo online účet) a poté zaplatíte pomocí bankovního účtu (Direct Pay) nebo platebního plánu. Architektura musí zvládnout jak životní cyklus faktury (vystavena, odeslána, po splatnosti, zaplacena), tak životní cyklus platby (zahájena, čeká na zpracování, vypořádána, selhala).

Pro B2B SaaS nebo vlastní webové aplikace často vytváříme fakturační modul, který generuje PDF a hostuje platební portál. Portál musí akceptovat více metod: kartu, peněženku nebo bankovní převod. Trik spočívá v propojení ID faktury s ID platební transakce v bráně a následném použití webhooků k aktualizaci stavu faktury. Častou chybou je spoléhat se na funkci hostované faktury platební brány, ale ztratit kontrolu nad párováním. Preferujeme ukládat vlastní záznamy o fakturách a bránu používat pouze jako platební procesor.

// Example webhook handler for invoice payment confirmation
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body;
  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    const invoiceId = session.metadata.invoice_id;
    await db.invoices.update({ id: invoiceId }, { status: 'paid' });
  }
  res.json({ received: true });
});

Výše uvedený kód je zjednodušený, ale ilustruje hlavní myšlenku: namapovat událost z brány na vlastní doménový model. Pole metadata je vaše záchrana. Bez něj byste museli dotazovat Stripe na párování relací, což přidává latenci a složitost.

Stav objednávky: Mapování platebních událostí na životní cyklus

Objednávka může projít mnoha stavy: pending_payment, payment_received, processing, fulfilled, cancelled. Platební událost by měla být jen jednou z mnoha spouštěčů. Klíčovým architektonickým rozhodnutím je, zda použít stavový automat nebo jednodušší pole stavu. Důrazně doporučujeme stavové automaty pro systémy s více než čtyřmi stavy nebo s komplexními přechody (např. objednávka může přejít z 'payment_received' do 'processing' do 'shipped', ale také z 'pending_payment' do 'cancelled'). Gem StateMachines v Rails nebo vlastní konečný stavový automat v Node.js fungují dobře.

Webhooky z platebních bran by měly vést přímo do stavového automatu. Například událost payment_intent.succeeded by měla převést objednávku z 'pending_payment' do 'payment_received'. Ale chraňte se před race conditions: pokud webhook dorazí dvakrát (většina bran garantuje doručení alespoň jednou), váš stavový automat musí být idempotentní – tj. přechod ze stejného aktuálního stavu do stejného následujícího stavu by měl být bez operace. Ukládáme event_id s každým webhookem pro deduplikaci.

Idempotence není volitelná. Pokud váš handler platebního webhooku není idempotentní, nakonec dvakrát naúčtujete zákazníkovi nebo vytvoříte falešné objednávky. Testovat to při běžné zátěži je těžké; simulujeme zpožděné a duplicitní webhooky v našem CI pipeline.

Stav objednávky je také potřeba vystavit zákazníkům. Jednoduchá stránka se stavem (např. progress bar) funguje, ale pouze pokud jsou základní přechody přesné. Viděli jsme systémy, kde frontend dotazuje API, které ukládá stav objednávky do mezipaměti – ale mezipaměť může být zastaralá, pokud webhook ještě nebyl zpracován. Řešením je použít real-time kanál (WebSocket nebo Server-Sent Events), který posílá změny stavu, takže se UI aktualizuje okamžitě po zpracování webhooku. Pro jednodušší projekty je přijatelná krátkodobá mezipaměť s TTL 30 sekund.

DigiForge radí: Vybudujte platební integrační vrstvu, ne chaos

Po integraci desítek platebních metod napříč projekty doporučujeme abstrahovat zpracování plateb za tenkou servisní vrstvu. Tato vrstva by měla normalizovat události každého poskytovatele plateb do společného formátu, řešit opakované pokusy a udržovat transakční log. Objednávkový systém nikdy nekomunikuje přímo se Stripe, Paytm nebo jiným vydavatelem – komunikuje s vaší platební službou. To výrazně usnadňuje přidávání nových platebních metod (například karty se stablecoinem) bez nutnosti zasahovat do logiky objednávek.

Dále doporučujeme považovat faktury za samostatnou doménu, nejen za stav objednávky. Faktura má svůj vlastní životní cyklus (návrh, odeslána, po splatnosti, zaplacena) a může být spojena s více objednávkami (např. měsíční předplatné). Podobně by měl být stav objednávky řízen stavovým automatem, který pokrývá všechny možné přechody, včetně částečných plateb, vratek a chargebacků.

Pokud budujete platební integraci od nuly, začněte mapováním všech platebních metod, které plánujete podporovat, a identifikujte společné události, které generují. Poté navrhněte svůj stavový automat a obsluhu webhooků. Pokud toto zvládnete, zbytek je už jen potrubí. Pokud byste chtěli druhý názor na svou architekturu, tým DigiForge už viděl dost okrajových případů, aby vám ušetřil pár bezesných nocí.