API płatności: jak przygotować bezpieczny przebieg integracji

Modeluj zamówienie i próbę jako różne obiekty

Zamówienie określa sprzedawane świadczenie, a próba płatności ma własny przebieg techniczny. Nadaj obu stabilne identyfikatory i przechowuj ich relację. Niejasny stan zamówienia nie powinien samoczynnie tworzyć kolejnej próby. Ustal też konto, sklep i środowisko wykorzystywane przez żądanie. Przy wielu sklepach wybór musi wynikać z zaufanych danych serwerowych, nie tylko z wartości edytowalnej w przeglądarce. Jawny model pozwala później odtworzyć, dlaczego użyto konkretnego połączenia, i pomaga przekazywać sprawy między zespołami bez niebezpiecznego upraszczania ich do jednej kwoty.

Integracja i API

Przekazuj kwotę zgodnie z kontraktem API

Każdy interfejs określa sposób przedstawienia wartości. Zastosuj dokładnie tę konwencję, zamiast przenosić format znany z innej integracji. OrsunPay dokumentuje kwoty jako ciągi dziesiętne. Sprawdź walutę i ostateczną wersję zamówienia przed wywołaniem. Zniżki oraz zmiany muszą być uwzględnione wcześniej. Prześledź przykładową kwotę od danych handlowych do wyniku i pokaż, gdzie odbywa się walidacja. Poprawnie wyglądający checkout nie wyklucza błędu przeliczenia, jeśli systemy inaczej interpretują liczby. Zapisana zasada ułatwia również przegląd kodu i diagnozę różnic wykrytych po uruchomieniu.

Hostowana strona płatności

Przewiduj utratę odpowiedzi bez ślepego ponawiania

Serwer może obsłużyć żądanie, mimo że odpowiedź nie dotrze do aplikacji. Wtedy nie wiadomo jeszcze, czy operacja istnieje. Ponowne utworzenie bez sprawdzenia może wygenerować duplikat. Użyj udokumentowanej idempotencji i zachowaj związek klucza z żądaniem biznesowym. Rozróżnij powtórzenie tego samego wywołania od świadomej nowej próby płatności. Nie pozwól, aby każdy klient API tworzył własną strategię odzyskiwania po przekroczeniu czasu. Wspólna reguła zapobiega sprzecznym działaniom i ułatwia ustalenie, który proces jest odpowiedzialny za rozpoznanie nieznanego wyniku.

Weryfikuj webhook przed zmianą zamówienia

Publiczny endpoint nie powinien ufać komunikatowi tylko dlatego, że ma oczekiwaną strukturę. Sprawdź podpis przed wykonaniem decyzji biznesowej. OrsunPay opisuje HMAC-SHA256 liczone na niezmienionych surowych bajtach treści. Przebudowanie lub formatowanie danych przed weryfikacją może zmienić wynik. Nie umieszczaj sekretów w kodzie przeglądarki i ogranicz dane poufne w logach. Dokumentacje Stripe i Mollie również podkreślają rolę serwerowych zdarzeń. Weryfikacja nadawcy i sposób rejestrowania komunikatu powinny być częścią projektu, a nie poprawką dodawaną dopiero po pierwszym nieoczekiwanym żądaniu.

Wykonuj skutek biznesowy tylko raz

Po sprawdzeniu technicznym aplikacja musi ustalić dozwolone przejście stanu. Ta sama informacja o sukcesie nie może wywołać dwóch wysyłek lub aktywacji. Zapisuj przetworzenie tak, aby duplikat był rozpoznawalny bez ponowienia skutku. Uwzględnij zdarzenia spóźnione. Strona powrotu może informować klienta, lecz sama nie jest dowodem zapłaty. Decyzja o realizacji powinna wynikać ze zweryfikowanego rezultatu serwera i reguł zamówienia. Dzięki temu proces pozostaje poprawny również wtedy, gdy kupujący nie wraca do aplikacji i nie może dostarczyć żadnego zrzutu ekranu.

Zaprojektuj przekazanie spraw do obsługi

Obsługa potrzebuje wyszukiwalnej referencji i zrozumiałego powodu pozostawienia sprawy otwartej. Opisz, kiedy można ponowić wewnętrzne przetwarzanie, a kiedy należy zwrócić się do PSP. OrsunPay łączy własne konta, ale nie zastępuje ich warunków ani decyzji akceptacyjnych. Potwierdź też publikację potrzebnego SDK lub pakietu przed uwzględnieniem go w harmonogramie. Kod w repozytorium nie dowodzi dostępności publicznej paczki. Przekazanie jest użyteczne, gdy inny pracownik potrafi zbadać przykładowy incydent z dostępnymi danymi i wyjaśnić klientowi znany etap bez zgadywania.

• Zasymuluj utraconą odpowiedź po utworzeniu operacji.
• Sprawdź nieprawidłowy podpis i duplikat komunikatu.
• Prześledź kwotę, walutę i kontekst sklepu.
• Zapisz procedurę obsługi nieznanych wyników.
• Używaj tych samych referencji w technice i obsłudze.

Źródła

• Dokumentacja Stripe dotycząca webhooków
• Dokumentacja Mollie dotycząca płatności