Wstęp
Integracja bramki płatniczej wydaje się prosta, gdy wszystko działa idealnie.
Klient klika “"Płacić."” Płatność powiodła się. Twój system otrzymał potwierdzenie. Zamówienie zostało oznaczone jako opłacone. Wszyscy są zadowoleni.
Prawdziwe systemy płatności nie mają szans na funkcjonowanie w tym świecie. Sieci zawodzą. Webhooki docierają z opóźnieniem. To samo zdarzenie jest dostarczane dwukrotnie. Klient odświeża stronę w trakcie realizacji transakcji. Bank żąda dodatkowego uwierzytelnienia. Bramka płatności przez jakiś czas oczekuje na potwierdzenie, zanim przekaże Ci jakiekolwiek ostateczne informacje.
Niezawodna integracja bramki płatniczej to coś więcej niż tylko okablowanie Stripe, Adyen, PayPal, Braintree, Przelewy24, PayU, lub dowolnego wybranego dostawcy. Prawdziwa praca polega na stworzeniu architektury, która pozostanie poprawna, gdy coś pójdzie nie tak, bo zawsze coś pójdzie nie tak.
Dla założycieli firm i kadry zarządzającej ma to duże znaczenie, ponieważ błędy w płatnościach są kosztowne. Podwójna opłata, nieopłacone zamówienie oznaczone jako opłacone lub nieudane odnowienie subskrypcji mogą natychmiast nadszarpnąć zaufanie. Użytkownicy wybaczają powolny ekran. Rzadko wybaczają problemy finansowe.
W Appricotsoft, podchodzimy do integracji płatności tak, jak do każdego systemu, w którym błędy kosztują realne pieniądze: planujemy tryby awarii przed napisaniem kodu i wbudowujemy kontrole jakości w przepływ pracy, zamiast dodawać je tuż przed uruchomieniem.
Dlaczego webhooki są ważne w integracji bramek płatniczych
Webhook to wiadomość, którą dostawca płatności wysyła do Twojego systemu, gdy wydarzy się coś ważnego. Na przykład:
- Płatność została autoryzowana.
- Płatność powiodła się.
- Płatność nie powiodła się.
- Utworzono zwrot pieniędzy.
- Otwarto procedurę obciążenia zwrotnego.
- Odnowienie subskrypcji nie powiodło się.
- Wypłata została zrealizowana.
Bez webhooków Twój system musiałby ciągle pytać dostawcę płatności, ”Czy coś się zmieniło?” To jest nieefektywne i nie sprawdza się na dużą skalę.
Nowoczesne bramki płatnicze w dużym stopniu opierają się na webhookach, ponieważ przepływy płatności są często asynchroniczne. Transakcja rzadko kończy się natychmiast. Banki, sieci kart płatniczych, kontrole oszustw, uwierzytelnianie 3D Secure, alternatywne metody płatności, portfele i lokalne metody płatności – wszystkie te czynniki mogą powodować opóźnienia lub stany pośrednie.
Na przykład Stripe wyjaśnia, że PaymentIntent może przechodzić przez wiele statusów w trakcie swojego cyklu życia, w tym uwierzytelnianie i etapy ostatecznego potwierdzenia. Adyen opisuje webhooki jako sposób, w jaki jego usługi mogą wysyłać komunikaty sterowane zdarzeniami do zdefiniowanego punktu końcowego, zamiast wymagać ciągłego odpytywania.
To sprawia, że webhooki są niezbędne. Ale to również sprawia, że są ryzykowne, jeśli się z nimi niewłaściwie obchodzimy.
Dlaczego webhooki płatnicze zawodzą
Awarie webhooka są częste i nie zawsze oznaczają niepowodzenie płatności. Zazwyczaj oznaczają one zerwanie komunikacji między systemami lub nieprawidłowe przetworzenie zdarzenia przez aplikację. Oto najczęstsze przyczyny.
1. Twój serwer jest tymczasowo niedostępny
Twój serwer może być wyłączony podczas wdrożenia, przeciążony lub mieć problem z infrastrukturą. Jeśli brama wyśle webhooka w tym czasie, możesz go nigdy nie otrzymać. Dobra integracja zakłada, że tak się stanie, bo tak właśnie będzie.
2. Punkt końcowy webhooka zwraca nieprawidłową odpowiedź
Większość dostawców oczekuje pomyślnej odpowiedzi HTTP po odebraniu webhooka przez punkt końcowy. Adyen zaleca akceptowanie webhooków z kodem stanu 2xx, zapisywanie wiadomości i późniejsze przetwarzanie jej zawartości.
Częstym błędem jest przetwarzanie wszystkiego przed udzieleniem odpowiedzi. Jeśli to przetwarzanie trwa zbyt długo, brama uznaje webhooka za nieudany i próbuje go ponownie wykonać, nawet jeśli system częściowo już wykonał akcję.
3. Wydarzenia pojawiają się więcej niż raz
Bramki płatności ponawiają próby obsługi webhooków, gdy nie otrzymają potwierdzenia. Oznacza to, że system może odebrać to samo zdarzenie dwa, trzy lub więcej razy. Jeśli kod nie jest idempotentny, zduplikowane webhooki zamieniają się w zduplikowane akcje: dwie faktury, dwa potwierdzenia zamówień, dwa e-maile, dwie aktualizacje salda portfela, dwie przesyłki.
4. Wydarzenia pojawiają się w niewłaściwej kolejności
Zdarzenia płatności nie zawsze pojawiają się w oczekiwanej kolejności. System może otrzymać zdarzenie “płatność pomyślnie zrealizowana” przed wcześniejszym zdarzeniem “przetwarzanie płatności”. Zdarzenie zwrotu może pojawić się, gdy pierwotna aktualizacja płatności jest jeszcze w trakcie realizacji. Dlatego logika statusu płatności powinna działać w oparciu o wyraźne zmiany stanu, a nie o zdarzenie, które nastąpiło jako ostatnie.
5. Twoja logika biznesowa zgłasza błąd
Czasami sam webhook działa prawidłowo, a Twój system ulega awarii podczas przetwarzania. Rekord zamówienia jeszcze nie istnieje. Blokada bazy danych blokuje działanie systemu. Powiązane konto użytkownika zostało usunięte. Usługa poczty e-mail jest niedostępna. Niezawodna integracja oddziela odbiór webhooka od przetwarzania biznesowego, dzięki czemu jedna tymczasowa awaria nie powoduje przerwania całego procesu płatności.
6. Weryfikacja bezpieczeństwa nie powiodła się
Webhooki powinny być weryfikowane, a większość dostawców obsługuje podpisy lub walidację HMAC. Jeśli weryfikacja się nie powiedzie z powodu błędnych haseł, rotacji kluczy lub niezgodności środowiska, system odrzuci zdarzenia, które były w rzeczywistości prawidłowe. Zjawisko to występuje regularnie, gdy zespoły przechodzą z piaskownicy do produkcji bez odpowiedniej listy kontrolnej uruchomienia.
Omówiliśmy szerszy problem związany z uruchomieniem w naszym powiązanym wpisie na temat list kontrolnych wdrażania bramki płatniczej, w którym punkty końcowe webhooków, klucze idempotentności, testowanie i monitorowanie uruchomienia są traktowane jako część gotowości do produkcji.
Co oznacza idempotencja w systemach płatności
Idempotentność oznacza, że ta sama operacja może być wykonywana wielokrotnie i nadal dawać ten sam wynik końcowy. W systemach płatności ma to większe znaczenie niż niemal wszystko inne w stosie.
Jeśli Twój system otrzyma ten sam webhook “płatność pomyślnie zrealizowana” trzy razy, nie powinien oznaczać tego samego zamówienia jako opłaconego trzy razy, tworzyć trzech faktur, wysyłać trzech e-maili z potwierdzeniem, dodawać środków do portfela trzy razy ani inicjować trzech wysyłek. Zamiast tego system powinien rozpoznać: To zdarzenie zostało już przetworzone lub to przeniesienie płatności. Nie ma potrzeby powtarzania tej czynności biznesowej.
Dokumentacja idempotencji firmy Stripe wyjaśnia, że klucze idempotencji pozwalają klientom bezpiecznie ponawiać żądania po błędach połączenia, bez przypadkowego wykonania tej samej operacji dwa razy. Stripe przechowuje pierwszy wynik dla danego klucza i zwraca ten sam wynik przy kolejnych próbach.
Idempotencja ma znaczenie w dwóch obszarach: żądaniach płatności wychodzących z systemu do bramki oraz obsłudze webhooków przychodzących z bramki do systemu. Większość zespołów zajmuje się pierwszym obszarem, a o drugim zapomina. Tu właśnie zaczynają się problemy.
Jak projektować idempotentne programy obsługi webhooków
Obsługujący webhook obiekt nie powinien po prostu odebrać zdarzenia i natychmiast uruchomić logiki biznesowej. Bezpieczniejszy projekt wygląda tak:
- Zweryfikuj podpis webhooka.
- Przechowuj surowe zdarzenie webhooka.
- Sprawdź czy to zdarzenie zostało już odebrane.
- Szybko odeślij pomyślnie zrealizowaną płatność do dostawcy usługi płatniczej.
- Przetwarzaj zdarzenie asynchronicznie.
- Aktualizuj stan płatności lub zamówienia tylko wtedy, gdy przejście jest prawidłowe.
- Zapisz wynik przetwarzania.
- Ponowna próba nie powiodła się, wewnętrzne przetwarzanie jest bezpieczne.
Dzięki temu masz kontrolę i przejrzystość sytuacji, zamiast czekać, aż wszystko pójdzie dobrze.
Najpierw przechowuj każde zdarzenie webhooka
Twój punkt końcowy webhooka powinien zapisać przychodzące zdarzenie przed wykonaniem jakichkolwiek skomplikowanych czynności. Dzięki temu Twój zespół będzie miał dostęp do śladu audytu i późniejsze debugowanie będzie znacznie mniej uciążliwe. Przechowuj pola takie jak:
- nazwa dostawcy,
- identyfikator zdarzenia dostawcy,
- identyfikator płatności,
- ID zamówienia,
- typ zdarzenia,
- znacznik czasu zdarzenia,
- surowy ładunek,
- wynik walidacji podpisu,
- status przetwarzania,
- liczba ponownych prób,
- komunikat o błędzie, jeśli przetwarzanie się nie powiedzie.
To nie jest przesadna inżynieria. To podstawowe bezpieczeństwo operacyjne.
Użyj identyfikatorów zdarzeń dostawcy jako unikalnych kluczy
Większość bramek zawiera unikalny identyfikator zdarzenia, a Twoja baza danych powinna wymuszać unikalność tego pola. Jeśli ten sam webhook pojawi się ponownie, system powinien go wychwycić i pominąć przetwarzanie duplikatów. Przykładowa logika:
- Wydarzenie odebrane po raz pierwszy → zapisz i przetwórz.
- Wydarzenie już istnieje i zostało przetworzone → zignoruj bezpiecznie.
- Wydarzenie już istnieje, ale zakończyło się niepowodzeniem → spróbuj ponownie przetworzyć, jeśli jest to dozwolone.
- Wydarzenie istnieje i jest obecnie przetwarzane → nie uruchamiaj na nim drugiego procesu roboczego.
Uczyń działania biznesowe również idempotentnymi
Samo usunięcie duplikatów zdarzenia webhooka nie wystarczy. Sama operacja biznesowa również musi być bezpieczna. Realizując zamówienie, sprawdź, czy zostało już opłacone, czy faktura już istnieje, czy e-mail z potwierdzeniem został już wysłany, czy zlecono już wysyłkę, czy dostęp użytkownika został już aktywowany.
Ma to znaczenie, ponieważ różne typy zdarzeń mogą wywołać tę samą akcję biznesową. Zdarzenie finalizacji zamówienia i zdarzenie pomyślnej płatności mogą sygnalizować gotowość zamówienia do realizacji. Twoja architektura musi zatrzymać podwójną realizację niezależnie od tego, które zdarzenie nastąpiło wcześniej.
Jak powinny działać ponowne próby
Ponowne próby są konieczne, ale muszą być kontrolowane, a nie pozostawione przypadkowi.
Integracja płatności składa się z dwóch warstw ponawiania prób: ponawiania prób webhooków w bramce do systemu oraz własnych, wewnętrznych prób przetwarzania logiki biznesowej. Nie masz pełnej kontroli nad pierwszą warstwą – dostawca decyduje, kiedy ponowić próbę dostarczenia – ale kontrolujesz reakcję swojego systemu.
Zwróć pomyślnie po zapisaniu webhooka.
W większości przypadków najlepszą praktyką jest walidacja i zapisanie webhooka, a następnie szybkie zwrócenie poprawnej odpowiedzi. Przetwarzanie odbywa się w tle. Dlaczego? Ponieważ jeśli wszystko przetwarzasz synchronicznie, chwilowa awaria w systemie może spowodować, że brama ponownie spróbuje użyć tego samego webhooka, co generuje szum, duplikaty i błędy, które trudno wyśledzić. Czystsze podejście:
- Punkt końcowy webhooka odbiera i weryfikuje zdarzenie.
- Zdarzenie jest przechowywane w tabeli skrzynki odbiorczej webhooka.
- Punkt końcowy zwraca odpowiedź 2xx.
- Pracownik w tle przetwarza zdarzenie.
- Nieudane przetwarzanie zostanie ponowione wewnętrznie.
Dzięki temu decyzja o czasie ponawiania prób, rejestrowaniu zgłoszeń i eskalacji znów leży w gestii Twojego zespołu.
Użyj wycofywania wykładniczego
Jeśli przetwarzanie wewnętrzne się nie powiedzie, nie próbuj ponownie od razu i w nieskończoność. Użyj wycofywania wykładniczego:
- Spróbuj ponownie za 1 minutę.
- Spróbuj ponownie za 5 minut.
- Spróbuj ponownie za 15 minut.
- Spróbuj ponownie za 1 godzinę.
- Oznacz jako nieudane i powiadom zespół.
Zapobiega to przekształceniu się poważnego incydentu w przeciążenie systemu.
Oddzielne awarie tymczasowe i trwałe
Nie każdy błąd wymaga ponownej próby. Tymczasowe błędy – takie jak przekroczenie limitu czasu bazy danych, awaria usługi poczty e-mail, niestabilne API bramy sieciowej lub przekroczenie limitu czasu kolejki roboczej – powinny zostać ponowione. Trwałe błędy – takie jak nieprawidłowy ładunek, nieznany dostawca płatności, nieprawidłowa konfiguracja waluty, brakujące zamówienie, które nigdy nie powinno się pojawić, lub nieudana walidacja podpisu – powinny zostać oznaczone, aby mógł je sprawdzić człowiek.
Przepływ referencyjny dla typowych statusów płatności
Każda bramka ma swoje własne nazwy zdarzeń, ale większość przepływów płatności jest odwzorowana na wspólny model statusu. Oto przykładowy przepływ, który sprawdza się u różnych dostawców.
Stworzony. Klient rozpoczyna proces płatności, a system tworzy lokalny rekord płatności. Podjęto próbę płatności, ale pieniądze nie zostały jeszcze przelane. Zarezerwuj zamówienie tymczasowo. Nie realizuj go.
Oczekujące lub przetwarzane. Płatność została zainicjowana, ale nie została sfinalizowana – co jest typowe dla przelewów bankowych, portfeli, alternatywnych metod płatności lub przepływów 3D Secure. Może się powieść lub nie. Wyświetl klientowi stan oczekujący i poczekaj na potwierdzenie.
Wymaga działania. Klient musi wykonać dodatkowy krok, zazwyczaj uwierzytelnienie 3D Secure. Płatność nie zostanie zrealizowana, dopóki tego nie zrobi. Poproś go o dokończenie.
Upoważniony. Kwota jest zarezerwowana, ale nie przechwycona – co jest typowe dla hoteli, targowisk, wypożyczalni i usług, gdzie ostateczne przechwycenie następuje później. Środki są zatwierdzane, a nie pobierane. W zależności od modelu biznesowego, potwierdź rezerwację lub dostępność, ale nie księguj ich jeszcze jako przychód.
Odniósł sukces lub został schwytany. Transakcja zakończona. Zrealizuj zamówienie, aktywuj usługę, wyślij paragon, zaktualizuj zapisy księgowe.
Przegrany. Płatność nie została zrealizowana. Powiadom klienta, pozwól mu spróbować ponownie i zachowaj zamówienie bez płatności.
Anulowane lub wygasłe. Sesja płatności lub intencja została anulowana lub przekroczyła limit czasu – albo klient ją porzucił, albo celowo ją anulowałeś. Zwolnij wszelkie zarezerwowane zasoby.
Zwrócono. Pieniądze zostały zwrócone klientowi w całości lub w części. Zaktualizuj zamówienie, zapisy księgowe, zasady komunikacji z klientem i zasady dostępu, jeśli którekolwiek z nich mają zastosowanie.
Sporne lub wymagające zwrotu pieniędzy. Klient zakwestionował transakcję. Jest ona w trakcie weryfikacji i może zostać cofnięta. Powiadom działy operacyjne, zbierz dowody i wstrzymaj realizację, jeśli ryzyko będzie tego wymagać.
Nie kopiuj statusów jednego dostawcy bezpośrednio do swojego produktu. Stwórz lokalny model statusów, który Twoja firma faktycznie rozumie, a następnie mapuj na niego zdarzenia dostawcy. Ma to jeszcze większe znaczenie, jeśli planujesz w przyszłości obsługiwać wiele bramek, krajów, walut lub metod płatności.
Praca związana z uzgadnianiem
Nawet przy hermetycznej obsłudze webhooków nadal konieczne jest uzgadnianie. Zadanie uzgadniania polega na porównaniu wewnętrznych rekordów z rekordami bramy i wykryciu niezgodności, takich jak:
- płatność została zrealizowana na bramce, ale Twoje zamówienie nadal nie zostało opłacone,
- zamówienie oznaczone jako opłacone, ale bramka informuje, że nie powiodło się,
- zwrot został zrealizowany, ale nigdy nie został uwzględniony w Twojej bazie danych,
- subskrypcja odnowiona, ale dostęp nigdy nie przedłużony,
- wypłata została utworzona, ale nie ma jej w raportach finansowych.
Pomiń to, a drobne niedopasowania pozostaną niezauważone, aż dział finansowy lub klient odkryją je w bolesny sposób.
Kiedy należy przeprowadzić uzgadnianie
W przypadku większości produktów uzgadnianie odbywa się według harmonogramu: co 15 do 60 minut w przypadku ostatnich płatności, codziennie w przypadku kontroli księgowych, co miesiąc w przypadku zamknięcia finansowego oraz ręcznie, gdy dział wsparcia zajmuje się konkretnym problemem. Dokładna częstotliwość zależy od wolumenu transakcji i tolerancji na ryzyko.
Co należy sprawdzić podczas uzgadniania
Przydatne zadanie polega na porównaniu lokalnego identyfikatora płatności, identyfikatora płatności dostawcy, kwoty, waluty, statusu płatności, kwoty przechwyconej, kwoty zwróconej, identyfikatora klienta, identyfikatora zamówienia, znaczników czasu i okresu subskrypcji, tam gdzie ma to znaczenie.
Gdy pojawi się niezgodność, nie zakładaj, że można ją bezpiecznie naprawić automatycznie i bez wiedzy użytkownika. Niektóre problemy można rozwiązać automatycznie. Inne wymagają najpierw interwencji człowieka. Na przykład: bramka informuje o płatności, system lokalny o oczekującym statusie – zazwyczaj można to bezpiecznie zaktualizować po weryfikacji. System lokalny informuje o płatności, bramka o niepowodzeniu – wymaga to zbadania. W przypadku niezgodności kwoty lub waluty należy natychmiast skontaktować się z kimś. Brakujące zamówienie, aby płatność została zrealizowana, wymaga zarówno wsparcia, jak i inżynierii.
Typowe błędy, których należy unikać
Większość problemów z wiarygodnością płatności bierze się z drobnych niedociągnięć, które na etapie projektowania wydawały się niegroźne.
Błąd 1: Zaufanie do potwierdzenia płatności w interfejsie użytkownika
Frontend nigdy nie powinien być ostatecznym źródłem prawdy. Wejście klienta na stronę potwierdzającą powodzenie transakcji nie gwarantuje jej faktycznego zrealizowania. Potwierdź poprzez zdarzenia backendowe, interfejsy API bramki płatniczej lub zweryfikowane webhooki – zawsze.
Błąd 2: Aktualizowanie zamówień bez sprawdzenia ich aktualnego stanu
Jeśli zamówienie jest już opłacone, drugie zdarzenie “płatność pomyślnie zrealizowana” nie powinno ponownie powodować realizacji. Sprawdź aktualny stan przed zastosowaniem jakiejkolwiek zmiany.
Błąd 3: traktowanie wszystkich zdarzeń webhook jako równie ważnych
Nie każde zdarzenie powinno zmieniać sytuację biznesową. Niektóre mają charakter informacyjny, inne wymagają natychmiastowego działania. Twój zespół musi jasno określić, które zdarzenia są istotne i jakie skutki każde z nich powinno przynieść.
Błąd 4: Brak pamięci zdarzeń webhooka
Jeśli nie przechowujesz webhooków, debugowanie zamienia się w zgadywanie. Będziesz wiedział, że coś jest nie tak, nie mając pojęcia, co bramka tak naprawdę Ci wysłała.
Błąd 5: Brak monitorowania i alertów
Problemy z płatnościami nie powinny zostać wykryte przez niezadowolonych klientów. Monitoruj nieudane przetwarzanie webhooków, wielokrotne próby, zablokowane oczekujące płatności, niezgodności w uzgadnianiu, wysoki wskaźnik nieudanych płatności i błędy przetwarzania zwrotów.
Błąd 6: Brak listy kontrolnej przejścia z piaskownicy do produkcji
Sekrety webhooków, adresy URL punktów końcowych, dozwolone metody płatności, waluty, adresy URL zwrotne, klucze API, ustawienia środowiska – wszystko to wymaga weryfikacji przed uruchomieniem. Właśnie w tym celu istnieje ustrukturyzowana lista kontrolna wdrożenia. Pominięcie jej powoduje, że drobne szczegóły konfiguracji przeciekają tuż przed rozpoczęciem płatności przez użytkowników.
Jak wygląda niezawodna architektura płatności
Konfiguracja gotowa do produkcji zazwyczaj obejmuje:
- Rekordy płatności w Twojej bazie danych.
- Identyfikatory płatności dostawców są przechowywane i indeksowane.
- Klucze idempotentności do tworzenia płatności wychodzących.
- Tabela skrzynki odbiorczej webhooku dla zdarzeń przychodzących.
- Walidacja podpisu.
- Unikalne identyfikatory zdarzeń dostawcy są wymuszane na poziomie bazy danych.
- Pracownicy w tle do przetwarzania webhooków.
- Przejrzysty wewnętrzny model statusu płatności.
- Zasady przejścia między stanami.
- Logika ponawiania prób z wycofaniem.
- Zadania związane z uzgadnianiem.
- Widoczność administracyjna dla zespołów wsparcia.
- Alerty dotyczące nieudanych lub podejrzanych płatności.
- Rejestry, które nie ujawniają poufnych danych dotyczących płatności.
To nie tylko kwestia inżynierii. Od tego zależy zaufanie klientów, przychody, działalność operacyjna, księgowość i zgodność z przepisami. Dla startupów, marketplace'ów, aplikacji fintech, platform hotelowych, systemów rezerwacyjnych, portfeli cyfrowych i produktów subskrypcyjnych niezawodność płatności jest częścią samego produktu – a nie szczegółem back-endu, którego użytkownicy nigdy nie widzą.
Jeśli użytkownicy nie mogą zaufać procesowi płatności, nie mogą też zaufać produktowi.
Jak budujemy niezawodne integracje płatności
W Appricotsoft nie traktujemy płatności jako zadania typu “podłącz API i idź dalej”. To podejście opiera się na tym samym modelu realizacji, który stosujemy w każdym projekcie: przewidywalny postęp, widoczne ryzyko, cotygodniowe demonstracje i kontrole jakości zintegrowane z codzienną pracą, a nie dodawane na końcu.
W przypadku usług integracji bramek płatniczych oznacza to skupienie się na przepływie użytkowników i stojącej za nim rzeczywistości operacyjnej.
1. Przed rozpoczęciem prac definiujemy przepływ płatności. Zanim zaczniemy pisać kod, ustalamy, jakie metody płatności są potrzebne – czy to płatność jednorazowa, subskrypcja, wypłata z platformy handlowej, doładowanie portfela, czy wstępna autoryzacja hotelu – co się dzieje, gdy płatność jest w toku, co się dzieje, gdy płatność się nie powiedzie, co muszą zobaczyć zespoły wsparcia oraz które zdarzenia uruchamiają realizację, a które jedynie aktualizują wewnętrzne rekordy. Błąd na początku może kosztować Cię później.
2. Projektujemy model statusu. Mapujemy statusy specyficzne dla dostawcy do modelu lokalnego, który Twój zespół może wykorzystać w praktyce. To się opłaca, zwłaszcza jeśli Twój produkt może ostatecznie korzystać z usług więcej niż jednego dostawcy. Twoja firma nie powinna być ograniczona do konwencji nazewnictwa jednej bramy.
3. Wprowadzamy idempotentność do przepływu pracy. Obsługujące je procesy zostały zaprojektowane do bezpiecznego przetwarzania powtarzających się zdarzeń, w oparciu o ograniczenia bazy danych, dzienniki zdarzeń, kontrole statusu oraz zabezpieczenia samych działań biznesowych. To samo zdarzenie nigdy nie powinno generować duplikatów działań finansowych lub operacyjnych.
4. Dodajemy ponowne próby i uzgadnianie. Zakładamy, że tymczasowe awarie się zdarzają, dlatego logika ponawiania prób i zadania związane z uzgadnianiem są częścią architektury od pierwszego dnia, a nie czymś dodawanym po incydencie.
5. Sprawdzamy przed uruchomieniem. Testujemy płatności pomyślne, nieudane, anulowane, oczekujące, ponowne próby obsługi webhooków, duplikaty zdarzeń, zdarzenia zwrotów i skrajne przypadki, o których nikt nie chce myśleć. W QA nie zatrzymujemy się na ścieżce do szczęścia. Sprawdzamy, jak system zachowuje się, gdy faktycznie pojawia się złożoność płatności.
6. Dbamy o przejrzystość procesu. Klienci widzą postępy dzięki ustrukturyzowanej realizacji, demonstracjom, dziennikom decyzji i bezpośredniej komunikacji – ponieważ integracja płatności wiąże się z wieloma kompromisami dotyczącymi szybkości, zakresu zgodności, kontroli UX, ograniczeń dostawcy i potrzeb operacyjnych, a kompromisy te muszą być widoczne, a nie odkrywane później.
Ukryte założenia to właśnie one prowadzą do kosztownych problemów produkcyjnych w projektach płatniczych. Dlatego staramy się ujawniać zakres i ograniczenia wcześnie, przed uruchomieniem, a nie po nim.
Wniosek
Webhooki i idempotencja to nie są drobiazgi. Jeśli się pomylisz, cały system – realizacja zamówień, księgowość, wsparcie – odziedziczy bałagan.
System płatności musi obsługiwać duplikaty zdarzeń, zdarzenia opóźnione, nieudane żądania, ponowne próby, zmiany statusu dostawcy, zwroty, spory i uzgadnianie. Pomiń którykolwiek z tych elementów, a produkt będzie wyglądał dobrze w wersji demonstracyjnej, ale w praktyce okaże się nieskuteczny w przypadku zachowań klientów.
Dla założycieli i kadry zarządzającej wniosek jest prosty: nie oceniaj jakości integracji płatności na podstawie tego, czy jedna transakcja testowa się powiodła. Oceniaj ją na podstawie tego, jak system radzi sobie z niepewnością. Niezawodna integracja powinna zawierać odpowiedzi na następujące pytania:
- Co się stanie, jeśli webhook dotrze dwa razy?
- Co się stanie, jeżeli przesyłka dotrze z opóźnieniem?
- Co się stanie, jeśli aktualizacja zamówienia się nie powiedzie?
- Co się stanie, jeśli bramka wskaże płatność, a nasz system wskaże oczekującą płatność?
- Co się stanie, jeśli zwrot zostanie utworzony ręcznie w panelu dostawcy?
- Co się stanie, jeśli dział wsparcia będzie musiał zbadać transakcję?
Odpowiedz na te pytania przed uruchomieniem, a nie po pierwszym zgłoszeniu pomocy technicznej.
Jeśli tworzysz integracje bramek płatniczych, aplikację fintech, portfel cyfrowy lub pracujesz nad integracją API płatności w szerszym zakresie, to właśnie tego typu problemy architektoniczne rozwiązujemy w Appricotsoft. Przepływ płatności, którego Twój zespół operacyjny nigdy nie musi rozwiązywać, to faktyczny produkt końcowy, a nie lista funkcji.
