Architektura integracji płatności: karty, portfele, faktury i status zamówienia

Integracja płatności rzadko bywa tak prosta, jak wrzucenie pojedynczego SDK. W naszych projektach w DigiForge widzieliśmy, jak zespoły rozrastały się, ponieważ nie doceniły złożoności obsługi wielu metod płatności — kart, portfeli cyfrowych, płatności fakturowych — a następnie powiązania ich wszystkich z cyklem życia zamówienia. Każdy typ płatności ma swoje osobliwości, a łączenie ich bez spójnej architektury prowadzi do kruchego kodu i bolesnego uzgadniania. Ten artykuł przedstawia, jak wygląda ujednolicona warstwa integracji płatności, opierając się zarówno na sprawdzonych wzorcach, jak i nowszych rozwiązaniach, takich jak karty oparte na stablecoinach.

Karty: Tokenizacja, tokeny sieciowe i rozwój kart opartych na stablecoinach

Płatności kartowe pozostają kręgosłupem e-commerce i wielu firm SaaS. Złotą zasadą jest nigdy nie obsługiwać surowych numerów kart. Tokenizacja za pośrednictwem bramki zgodnej z PCI (Stripe, Braintree, Adyen) to podstawa. Ale istnieje subtelniejsza warstwa: tokeny sieciowe. Są to tokeny specyficzne dla urządzenia, jednorazowe, wydawane przez same sieci kartowe, oferujące lepsze wskaźniki autoryzacji i mniejsze oszustwa. Zwykle namawiamy klientów do wczesnego wdrożenia tokenizacji sieciowej, zwłaszcza jeśli przetwarzają płatności cykliczne, ponieważ żywotność tokenów jest dłuższa, a aktualizacje są obsługiwane przez sieć.

Nową falą jest karta oparta na stablecoinach. Pod koniec 2025 roku wolumen kart kryptowalutowych osiągnął roczny wskaźnik 18 miliardów dolarów, rosnąc o 106% rocznie od 2023 roku (komunikat prasowy Wirex/Crossmint). Architektura jest tutaj inna: zamiast pobierać środki z konta bankowego lub linii kredytowej, karta korzysta z portfela stablecoinów. Dla programistów oznacza to integrację z dostawcą portfela (np. inteligentny portfel Crossmint) i emitentem karty (np. Wirex). Wyzwaniem jest zgodność — komunikat prasowy zauważa, że fintechy wcześniej musiały samodzielnie składać portfel, emitenta i ramy zgodności. W DigiForge pracowaliśmy nad podobnymi integracjami wielu dostawców i odkryliśmy, że warstwa abstrakcji z ujednoliconym modelem transakcji jest niezbędna. W przeciwnym razie debugowanie nieudanej płatności staje się gonitwą po trzech panelach dostawców.

Portfele cyfrowe: UPI, Google Pay oraz integracja hostowana vs. oparta na API

Portfele cyfrowe nie są monolitem. Google Pay (obecnie część szerszego ekosystemu Google Payments) działa inaczej niż indyjskie portfele oparte na UPI, takie jak Paytm, a oba różnią się od portfeli specyficznych dla aplikacji. Decyzja architektoniczna sprowadza się do wyboru między hostowanym checkoutem (prostszym, ale z mniejszą kontrolą) a integracją opartą na API (bardziej złożoną, ale bogatszą w UX).

W przypadku portfeli takich jak Google Pay, Apple Pay i PayPal, typowym wzorcem jest przycisk portfela, który otwiera arkusz lub przekierowuje. Integracja odbywa się zazwyczaj przez ujednolicony checkout bramki płatności – na przykład Stripe Payment Element automatycznie renderuje wszystkie portfele. To rozwiązanie jest wystarczające w wielu przypadkach, ale napotkaliśmy ograniczenia, gdy potrzebne jest niestandardowe stylowanie lub zebranie dodatkowych danych przed płatnością. Głębsza integracja przez własne SDK portfela daje większą kontrolę, ale wymaga utrzymywania oddzielnych ścieżek kodu.

Portfele oparte na UPI, takie jak Paytm, działają inaczej. UPI (Unified Payments Interface) to system płatności natychmiastowych umożliwiający bezpośrednie przelewy między bankami. Integrując Paytm jako metodę płatności, typowy przepływ wygląda następująco: użytkownik wybiera Paytm, backend generuje żądanie płatności, użytkownik autoryzuje w aplikacji Paytm, a Paytm wysyła callback. Wyzwaniem jest tutaj idempotentność – płatności UPI mogą zakończyć się sukcesem po stronie banku, ale zgłosić błąd do sprzedawcy z powodu przekroczenia czasu sieci. Zawsze budujemy zadanie uzgadniające, które co kilka minut porównuje status naszego zamówienia ze statusem transakcji w Paytm.

Faktury: Żądania płatności i uzgadnianie

Płatności fakturowane – w przypadku których firma wystawia rachunek, a klient płaci później – wprowadzają inny zestaw problemów. Strona IRS Payments (irs.gov/payments) jest przykładem systemu fakturowania na dużą skalę: sprawdzasz swoje saldo (poprzez powiadomienie lub konto online), a następnie płacisz za pomocą konta bankowego (Direct Pay) lub planu ratalnego. Architektura musi obsługiwać zarówno cykl życia faktury (wystawiona, wysłana, przeterminowana, opłacona), jak i cykl życia płatności (zainicjowana, oczekująca, rozliczona, nieudana).

W przypadku oprogramowania B2B SaaS lub niestandardowych aplikacji internetowych często budujemy moduł fakturowania, który generuje pliki PDF i udostępnia portal płatności. Portal musi akceptować wiele metod: kartę, portfel lub przelew bankowy. Sztuczka polega na powiązaniu identyfikatora faktury z identyfikatorem transakcji płatności w bramce, a następnie użyciu webhooków do aktualizacji statusu faktury. Częstym błędem jest poleganie na funkcji fakturowania hostowanej przez bramkę płatności, ale utrata kontroli nad uzgadnianiem. Wolimy przechowywać własne rekordy faktur i używać bramki wyłącznie jako procesora płatności.

// 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 });
});

Powyższy kod jest uproszczony, ale ilustruje główną ideę: mapowanie zdarzenia bramki na własny model domeny. Pole metadanych jest twoją deską ratunku. Bez niego musiałbyś odpytywać Stripe w celu dopasowania sesji, co zwiększa opóźnienie i złożoność.

Status zamówienia: mapowanie zdarzeń płatności na cykl życia

Zamówienie może przechodzić przez wiele statusów: pending_payment, payment_received, processing, fulfilled, cancelled. Zdarzenie płatności powinno być tylko jednym z wielu wyzwalaczy. Kluczową decyzją architektoniczną jest wybór między maszyną stanów a prostszym polem statusu. Zdecydowanie preferujemy maszyny stanów dla systemów z więcej niż czterema statusami lub złożonymi przejściami (np. zamówienie może przejść z 'payment_received' do 'processing' do 'shipped', ale także z 'pending_payment' do 'cancelled'). Gem StateMachines w Rails lub niestandardowa skończona maszyna stanów w Node.js sprawdzają się dobrze.

Webhooki z bramek płatności powinny bezpośrednio zasilać maszynę stanów. Na przykład zdarzenie payment_intent.succeeded powinno przejść zamówienie z 'pending_payment' do 'payment_received'. Należy jednak zabezpieczyć się przed warunkami wyścigu: jeśli webhook dotrze dwukrotnie (większość bramek gwarantuje dostarczenie co najmniej raz), maszyna stanów musi być idempotentna – czyli przejście z tego samego bieżącego stanu do tego samego następnego stanu powinno być bezoperacyjne. Przechowujemy event_id z każdym webhookiem w celu deduplikacji.

Idempotentność nie jest opcjonalna. Jeśli twój handler webhooka płatności nie jest idempotentny, prędzej czy później podwójnie obciążysz klienta lub utworzysz widmowe zamówienia. Testowanie tego przy normalnym obciążeniu jest trudne; symulujemy opóźnione i zduplikowane webhooki w naszym potoku CI.

Status zamówienia musi być również udostępniany klientom. Prosta strona statusu (np. pasek postępu) działa, ale tylko jeśli podstawowe przejścia są dokładne. Widzieliśmy systemy, w których frontend odpytywał API z buforowaniem statusu zamówienia – ale pamięć podręczna może być nieaktualna, jeśli webhook nie został jeszcze przetworzony. Rozwiązaniem jest użycie kanału czasu rzeczywistego (WebSocket lub Server-Sent Events), który wypycha zmiany statusu, dzięki czemu interfejs użytkownika aktualizuje się natychmiast po przetworzeniu webhooka. W przypadku prostszych projektów akceptowalna jest krótkotrwała pamięć podręczna z TTL wynoszącym 30 sekund.

Stanowisko DigiForge: Zbuduj warstwę integracji płatności, a nie bałagan

Po zintegrowaniu dziesiątek metod płatności w różnych projektach, naszą radą jest abstrakcja przetwarzania płatności za pomocą cienkiej warstwy usługowej. Warstwa ta powinna normalizować zdarzenia każdego dostawcy płatności do wspólnego formatu, obsługiwać ponowne próby oraz prowadzić dziennik transakcji. System zamówień nigdy nie komunikuje się bezpośrednio ze Stripe, Paytm czy innym wystawcą – rozmawia z twoją usługą płatności. To znacznie ułatwia dodawanie nowych metod płatności (np. karty stablecoin) bez ingerencji w logikę zamówień.

Zalecamy również traktowanie faktur jako osobnej domeny, a nie tylko statusu zamówienia. Faktura ma swój własny cykl życia (szkic, wysłana, przeterminowana, opłacona) i może być powiązana z wieloma zamówieniami (np. miesięczna subskrypcja). Podobnie status zamówienia powinien być sterowany przez maszynę stanów obsługującą wszystkie możliwe przejścia, w tym płatności częściowe, zwroty i obciążenia zwrotne.

Jeśli budujesz integrację płatności od zera, zacznij od mapowania wszystkich metod płatności, które planujesz obsługiwać, i zidentyfikuj wspólne zdarzenia, które one emitują. Następnie zaprojektuj swoją maszynę stanów i handler webhooków. Jeśli to zrobisz dobrze, reszta to tylko hydraulika. Jeśli chcesz uzyskać drugą opinię na temat swojej architektury, zespół DigiForge widział wystarczająco wiele przypadków brzegowych, by oszczędzić ci kilku nieprzespanych nocy.