Webhooki i rozliczenia w płatnościach agentowych — bez zgubionych transakcji

Płatność, którą inicjuje agent AI, nie kończy się w momencie kliknięcia „zapłać”. Kończy się dopiero wtedy, gdy masz pewność, że pieniądze faktycznie zmieniły właściciela, że stało się to dokładnie raz i że potrafisz po fakcie wskazać, kto, komu, ile, kiedy i na jakiej podstawie zapłacił. Ta część stosu — webhooki i rozliczenia — decyduje o tym, czy system jest godny zaufania, czy generuje ciche straty.

W skrócie: rozliczanie płatności agenta opiera się na trzech filarach. Po pierwsze, webhooki od dostawcy płatności informują o zmianach statusu (sukces, niepowodzenie, zwrot, spór). Po drugie, idempotencja chroni przed podwójnym obciążeniem, gdy agent ponawia żądanie. Po trzecie, reconciliation — uzgadnianie zdarzeń dostawcy z własnym logiem decyzji agenta — daje audytowalny ślad, w którym każda płatność ma przypisaną intencję i mandat. Bez tych trzech elementów transakcje zaczynają „znikać”: obciążenia bez zamówień, zamówienia bez obciążeń, zwroty, których nikt nie odnotował.

Dlaczego rozliczenia agenta to inny problem niż klasyczny checkout?

W zwykłym sklepie płatność inicjuje człowiek. Jeśli coś pójdzie nie tak, klient widzi błąd, odświeża stronę i próbuje ponownie — świadomie. Agent działa inaczej. Pętla agenta jest automatyczna i uparta: po timeoucie połączenia, błędzie 500 czy zerwanej sieci agent ponowi próbę bez wahania, bo taka jest jego logika. To właśnie ta automatyczna konsekwencja, pożądana przy realizacji zadania, staje się zagrożeniem przy pieniądzach.

Drugi czynnik to asynchroniczność. Agent może zainicjować płatność, dostać odpowiedź „przetwarzam”, a ostateczny status poznać dopiero kilka sekund lub minut później. W tym oknie agent nie powinien zgadywać — powinien czekać na potwierdzone zdarzenie. Stąd centralna rola webhooków.

Jak działają webhooki i czemu nie wolno im ślepo ufać?

Webhook to powiadomienie, które dostawca płatności wysyła na Twój endpoint, gdy zmienia się stan transakcji. Zamiast nieustannie odpytywać API („czy już zapłacono?”), Twój system nasłuchuje i reaguje na zdarzenia w rodzaju payment.succeeded, payment.failed, charge.refunded czy charge.dispute.created. Model ten dobrze opisuje dokumentacja webhooków Stripe, która jest praktycznym wzorcem dla większości dostawców.

Webhook jest jednak tylko sygnałem, a nie wyrocznią. Trzy zasady, które trzeba wdrożyć od pierwszego dnia:

• Weryfikuj podpis. Każde przychodzące zdarzenie podpisuj sekretem webhooka i odrzucaj wszystko, co podpisu nie przejdzie. Bez tego endpoint przyjmie spreparowane „potwierdzenie płatności” od dowolnego nadawcy.
• Odpowiadaj szybko, przetwarzaj później. Odbierz zdarzenie, zapisz je i natychmiast zwróć 200. Ciężką logikę (uzgadnianie, wysyłka, księgowanie) wykonuj w tle. Dostawcy ponawiają dostarczenie, jeśli endpoint odpowiada wolno albo błędem — a ponowienie to kolejna okazja do podwójnego przetworzenia.
• Zakładaj, że webhook może nie dotrzeć albo dotrzeć dwa razy. Sieć zawodzi. Dlatego źródłem prawdy o statusie płatności niech będzie odpytanie API dostawcy, a nie sama treść webhooka. Webhook mówi „sprawdź transakcję X”, a Ty sprawdzasz ją u źródła.

Idempotencja: jak nie obciążyć klienta dwa razy?

Idempotencja to właściwość operacji, która wykonana wielokrotnie daje ten sam skutek, co wykonana raz. W płatnościach oznacza to: jeśli agent wyśle to samo żądanie obciążenia dwa razy, pieniądze zostaną pobrane tylko raz.

Mechanizm jest prosty w idei. Przed wysłaniem żądania płatności agent generuje klucz idempotentny — unikalny identyfikator powiązany z konkretną intencją zakupową (na przykład „zapłać za zamówienie #4471”). Klucz ten wędruje w nagłówku żądania do dostawcy. Jeśli żądanie dotrze po raz drugi z tym samym kluczem, dostawca nie tworzy nowej płatności, tylko zwraca wynik tej pierwszej.

Kluczowa zasada projektowa: klucz idempotentny musi być stabilny w obrębie jednej intencji, a nie generowany od nowa przy każdym ponowieniu. Jeśli agent przy każdej próbie losuje nowy klucz, ochrona znika. Dlatego klucz powinien wynikać z czegoś trwałego — identyfikatora zamówienia, hasza koszyka czy ID mandatu — i być zapisany po stronie agenta, zanim poleci pierwsze żądanie.

Bez idempotencji	Z idempotencją
Timeout → agent ponawia → dwa obciążenia	Timeout → agent ponawia z tym samym kluczem → jedno obciążenie
Trudno ustalić, czy płatność przeszła	Status pierwszej próby zwracany deterministycznie
Zwroty i reklamacje od klientów	Cisza — bo nie ma czego reklamować

Reconciliation: jak połączyć płatność z decyzją agenta?

Uzgadnianie (reconciliation) to czynność łączenia dwóch niezależnych zapisów: strumienia zdarzeń od dostawcy (co faktycznie wydarzyło się z pieniędzmi) oraz logu decyzji agenta (dlaczego płatność miała się wydarzyć). Dopiero ich zestawienie daje pełny obraz.

Po stronie dostawcy masz fakty finansowe: kwota, waluta, status, znacznik czasu, identyfikator transakcji. Po stronie agenta masz kontekst decyzyjny: jaką intencję realizował, na podstawie jakiego mandatu działał, jaki był limit, kto był odbiorcą i jaki produkt został kupiony. Spięcie obu po wspólnym kluczu (najczęściej identyfikator zamówienia albo klucz idempotentny) pozwala odpowiedzieć na pytanie audytowe: kto, komu, ile, kiedy i na jakiej podstawie.

Praktyczny model reconciliation wygląda tak:

1. Wspólny klucz korelacji. Każda płatność niesie identyfikator, który istnieje po obu stronach. Bez niego uzgadnianie zamienia się w zgadywanie po kwocie i czasie.
2. Trzy kategorie rozjazdów. Job uzgadniający dzieli przypadki na: obciążenie bez pasującego logu agenta (skąd ta płatność?), log agenta bez obciążenia (czy płatność utknęła, czy się nie powiodła?) oraz rozjazd kwoty (agent chciał zapłacić X, pobrano Y).
3. Okresowy przebieg kontrolny. Niezależnie od webhooków uruchamiaj cykliczny job, który odpytuje dostawcę o transakcje z danego okna i porównuje je z własnym stanem. To siatka bezpieczeństwa na pominięte zdarzenia.

Reguła brzmi: webhooki dają reakcję w czasie zbliżonym do rzeczywistego, a okresowy job daje pewność. Dopiero oba mechanizmy razem eliminują „zgubione” transakcje. Sam log decyzji agenta i jego rola dowodowa to temat, który rozwijamy w materiale o budowaniu kompletnego, audytowalnego śladu transakcji.

Jak obsłużyć zwroty i spory bez utraty śladu?

Zwrot (refund) i spór (dispute, chargeback) to zdarzenia, które przychodzą po zakończonej płatności, często z dużym opóźnieniem, i również trafiają do Ciebie jako webhooki. Tu najłatwiej zgubić spójność, bo pierwotna decyzja agenta jest już dawno za nami.

Zasady, które warto przyjąć:

• Zwrot to nowe zdarzenie, nie skasowanie poprzedniego. Nie nadpisuj pierwotnego obciążenia. Dopisz powiązany rekord zwrotu z własnym kluczem idempotentnym — żeby ponowione żądanie zwrotu też nie wykonało się dwa razy.
• Powiąż zwrot z tą samą intencją. Zwrot ma odsyłać do oryginalnej płatności i jej mandatu. Dzięki temu w audycie widać pełną historię: agent kupił na podstawie mandatu M, a potem nastąpił zwrot Z z powodu P.
• Spory traktuj jako sygnał dla człowieka. Chargeback rzadko da się rozstrzygnąć automatycznie. Rola systemu agentowego to dostarczenie dowodów: zapisu intencji, mandatu, znaczników czasu i potwierdzenia realizacji. Tu audytowalny log z reconciliation spłaca się bezpośrednio.

Audytowalny zapis jako fundament całości

Wspólnym mianownikiem webhooków, idempotencji i reconciliation jest niezmienny, audytowalny zapis każdego zdarzenia. Dla każdej płatności powinieneś móc odtworzyć łańcuch: intencja agenta → mandat i limit → wysłane żądanie z kluczem idempotentnym → zdarzenia od dostawcy → ewentualny zwrot lub spór. Każdy element opatrzony znacznikiem czasu i niemodyfikowalny po zapisie.

Taki zapis nie jest formalnością. To on pozwala odpowiedzieć kontrolerowi, klientowi i samemu sobie na pytanie, czy konkretne pieniądze wyszły zgodnie z udzielonym upoważnieniem. Jak ten ślad wpina się w resztę architektury — od warstwy mandatów po wykonanie płatności — opisujemy w przewodniku o warstwach stosu agenta zdolnego do płacenia.

Webhooki bez idempotencji prowadzą do podwójnych obciążeń. Idempotencja bez reconciliation ukrywa rozjazdy. Reconciliation bez audytowalnego logu nie wytrzymuje pierwszego sporu. Dopiero złożone razem dają system, w którym żadna transakcja agenta nie ginie — i w którym każdą można obronić.