Jak dodać tryb testowy płatności

Tryb testowy płatności pozwala wdrożyć i sprawdzić proces transakcji bez obciążania prawdziwych kart czy rachunków. Dzięki niemu zespoły programistyczne i operacyjne mogą bezpiecznie przetestować ścieżki zakupowe, zwroty, błędy oraz zdarzenia asynchroniczne, zanim trafią na produkcję. Poniższa instrukcja przeprowadzi Cię krok po kroku przez przygotowanie środowiska, konfigurację kluczy, implementację najważniejszych przepływów oraz zestaw testów, które warto uruchamiać przed przełączeniem na realne rozliczenia.

Plan i założenia: jak projektować tryb testowy od początku

Definicja i cele trybu testowego

Tryb testowy to środowisko sandbox od dostawcy płatności oraz konfiguracja Twojej aplikacji, która kieruje żądania do testowych endpointów i używa testowych danych. Celem jest realistyczna integracja z bramką płatniczą: od utworzenia zamówienia, przez autoryzacja, po rozliczenie, zwrot i zdarzenia pochodzące od bramki. W testach sprawdzasz nie tylko ścieżkę szczęśliwą, ale i zachowania błędowe, w tym odmowy, wygaśnięcie sesji 3‑D Secure, niespójność kwot czy przerwanie procesu po stronie klienta.

Zakres i minimalny zestaw funkcji do przetestowania

• Metody płatności: karta, przelew ekspresowy, portfele (Apple Pay/Google Pay), BLIK, płatności odroczone.
• Tryby rozliczeń: autoryzacja i późniejsze capture, natychmiastowe capture, częściowe obciążenia.
• Przepływy negatywne: odmowa banku, brak środków, błąd 3‑D Secure/SCA, timeout bramki.
• Operacje po transakcji: refundacje częściowe i pełne, ponowienia płatności, chargeback.
• Zdarzenia asynchroniczne: webhooki o statusach płatności, zwrotach, sporach.

Architektura środowisk i izolacja danych

Zaprojektuj minimum trzy środowiska: lokalne dev, test/stage, oraz produkcja. W module płatności przewidź przełącznik, który zmienia:

• Adresy endpointów API bramki.
• Zestaw kluczy (public/secret) oraz identyfikatory jak merchant_id.
• Źródła danych testowych: numery kart testowych, kody BLIK testowe, konta wirtualne.

Izoluj logi i bazy danych, aby transakcje z testów nie mieszały się z produkcją. W praktyce stosuj osobne projekty w chmurze, prefiksy tabel oraz tagowanie metadanych transakcji, np. mode=test.

Dobór dostawcy płatności i strategia wielobramkowa

Jeżeli planujesz więcej niż jednego dostawcę, opracuj spójny interfejs w aplikacji: jednolitą warstwę adapterów mapującą różne API na wspólny model. Dzięki temu w trybie testowym możesz równolegle uruchomić symulacje kilku bramek i łatwiej porównać wyniki. Zaplanuj też politykę failover: jeśli bramka A jest niedostępna, testuj automatyczne przełączenie na bramkę B w środowisku testowym zanim zaufasz temu mechanizmowi na produkcji.

Konfiguracja środowiska i kluczy dostępowych

Tworzenie konta testowego u dostawcy

Załóż konto w panelu dostawcy płatności i włącz środowisko testowe. Przykłady:

• Stripe: Dashboard → Developers → Test mode. Generujesz Publishable key i Secret key dla testów.
• PayU: Panel Merchant → Środowisko testowe → Identyfikatory pos/pos_auth_key.
• Przelewy24: Panel → Dane testowe → Klucze i konfiguracja URL zwrotnych.
• PayPal: Developer Dashboard → Sandbox → Accounts & REST Apps.

Upewnij się, że masz dostęp do narzędzi dekodowania i weryfikacji podpisów webhooków, a w razie potrzeby pobierz certyfikaty dostawcy.

Bezpieczne przechowywanie kluczy i zmienne środowiskowe

Klucze trzymaj poza repozytorium. Użyj menedżera sekretów lub zmiennych środowiskowych: na lokalnym dev plik .env, na serwerach menedżer chmurowy. Nazwy typu PAYMENT_MODE=test, PAYMENT_PROVIDER=stripe, PAYMENT_SECRET=… Ustaw uprawnienia tylko dla procesów, które muszą je czytać. Konsekwentnie oddzielaj klucze testowe od produkcyjnych, aby uniknąć przypadkowego ruchu na realnych kartach.

Konfiguracja endpointów i adresów zwrotnych

W testach ustaw:

• Adresy API sandbox dostawcy, zgodne z dokumentacją.
• Adresy URL webhooków wskazujące na testową domenę lub tunel do środowiska lokalnego (np. ngrok, cloudflared), aby odbierać zdarzenia.
• Obsługę nagłówków autoryzacyjnych i weryfikacji podpisów, identyfikatory jak merchant_id oraz profile płatności przypisane do środowiska testowego.

W panelu bramki zweryfikuj, że Twoje adresy zwrotne odpowiadają 200 OK i że system widzi je jako aktywne. Włącz idempotency key w żądaniach tworzonych z frontendu i backendu.

Dane testowe: karty, BLIK i przelewy

Każdy dostawca udostępnia katalog testowych danych. Znajdziesz tam numery kart z różnymi wynikami 3‑D Secure i odmowami, kody BLIK działające w testach, IBAN-y do przelewów wirtualnych, a także konta sandbox dla PayPal. Zbierz je do jednego zestawu dla QA i opisz zasady użycia. Ustal, jak symulować różne waluty i strefy SCA, np. testy klienta z EOG vs poza EOG.

Kontrola wersji, feature flagi i automatyzacja

Wprowadź flagę feature: payments.test_mode.enabled. W CI skonfiguruj stage, który automatycznie deployuje aplikację w trybie testowym i uruchamia pakiet testów. Każda zmiana w module płatności powinna uruchamiać pipeline, który tworzy środowisko tymczasowe, wykonuje testy jednostkowe, kontraktowe i E2E, a następnie raportuje wyniki do zespołu.

Implementacja przepływów płatniczych w trybie testowym

Tworzenie transakcji: od koszyka do autoryzacji

Podziel logikę na etap pre‑payment i payment:

• Pre‑payment: walidacja koszyka, kalkulacja podatków, wygenerowanie internal order_id, zapis w bazie z flagą test.
• Payment: utworzenie płatności w bramce, przekierowanie lub wyświetlenie komponentu do danych karty, wsparcie SCA, przechwycenie wyniku.

W trybie testowym upewnij się, że parametry amount, currency i reference są spójne po obu stronach. Dla kart zastosuj strategię decoupled: tokenizacja danych w przeglądarce (np. przez SDK dostawcy), a serwer operuje na tokenie i nie przetwarza wrażliwych danych karty.

Autoryzacja vs capture i częściowe obciążenia

Jeśli model biznesowy wymaga wysyłki później, włącz flow auth‑then‑capture:

• Auth: rezerwacja środków na karcie klienta.
• Capture: pełne lub częściowe obciążenie przy kompletacji zamówienia.

W testach sprawdź wygasanie autoryzacji, wielokrotne capture dla kilku pozycji i zwolnienie środków po anulowaniu. Symuluj też błąd capture po stronie dostawcy, a następnie ponów operację z idempotency key.

Obsługa zdarzeń asynchronicznych i idempotencja

Włącz odbiór zdarzeń poprzez webhooki. Każdy event weryfikuj podpisem i przechowuj w trwałej kolejce, aby zapewnić dostarczenie i przetwarzanie w odpowiedniej kolejności. Dodaj idempotency key do operacji serwerowych, aby uniknąć podwójnych obciążeń przy retry. W testach sztucznie generuj opóźnienia i duplikaty eventów, sprawdzając, czy mechanizm de‑duplikacji działa prawidłowo.

SCA i 3‑D Secure

Przygotuj interfejs użytkownika na różne warianty SCA: challenge z przekierowaniem, osadzone okno, frictionless. W katalogu danych testowych znajdziesz karty, które wymuszają challenge, odmowę, a nawet błąd powiązany z upłynięciem czasu. Zweryfikuj, że UI zawsze pozwala wrócić do koszyka lub spróbować ponownie.

Subskrypcje, płatności cykliczne i aktualizacja tokenów

W modelu cyklicznym testuj:

• Utworzenie instrumentu płatniczego i jego automatyczne odświeżanie.
• Obciążenia co okres rozliczeniowy, próby ponowienia przy braku środków.
• Zmianę planu, częściowe okresy, proporcjonalne rozliczenia.

Upewnij się, że Twoje cron joby lub kolejki zadaniowe działają z danymi testowymi i nie wysyłają maili produkcyjnych. Jeśli dostawca wspiera account updater, przetestuj scenariusz, w którym karta zmienia datę ważności.

Zwroty, spory i chargeback

Zapewnij pełną obsługę operacji po transakcji: pełne i częściowe refundacje, anulowanie obciążenia przed rozrachunkiem, obsługa sporów. W testach wymuś spór, sprawdź, czy system blokuje ponowne wysyłki, aktualizuje status zamówienia i księguje korekty. Dodaj dowody i notatki zgodnie z wymaganiami bramki.

Odporność na błędy, time‑out i ponowienia

Wprowadź politykę retry z backoff i limitami. Rozróżniaj błędy trwałe (4xx) od tymczasowych (5xx, time‑out). Testuj scenariusze: zniknięcie połączenia w trakcie autoryzacji, otrzymanie webhooks przed odpowiedzią z API, odpowiedzi 202 Accepted, które wymagają późniejszego potwierdzenia.

Testy E2E, bezpieczeństwo i operacje po wdrożeniu

Zestaw scenariuszy E2E do uruchamiania w CI

Przygotuj automatyczne testy E2E uruchamiane przy każdym wydaniu. Scenariusze:

• Zakup jednego produktu kartą z powodzeniem, z SCA i bez SCA.
• Odmowa banku i powrót do koszyka, brak obciążenia w systemie.
• Płatność BLIK, błędny kod i ponowienie.
• Capture częściowy i późniejszy zwrot częściowy.
• Subskrypcja miesięczna, brak środków w trzecim cyklu, ponowienie po 24 h.
• Przerwanie procesu przez zamknięcie przeglądarki oraz wznowienie po webhooku paid.

Zadbaj o tagowanie testów według ryzyka i krytyczności oraz o raporty z przebiegu w pipeline.

Rekonsyliacja i raporty

W testach uruchom proces dopasowywania zamówień do transakcji w bramce oraz generowanie raportów dziennych. Sprawdź zgodność kwot, walut i kursów. W trybie testowym wiele bramek udostępnia fikcyjne raporty wypłat i rozliczeń — użyj ich, aby zasymulować pełen cykl księgowy i integrację z ERP.

Obserwowalność i alerty

Włącz logowanie wrażliwych punktów integracji, maskując dane osobowe oraz PAN. Zbierz metryki: czas autoryzacji, skuteczność, RTO webhooków, skuteczność retry. Ustaw alerty przy odchyleniach. Zadbaj o monitoring w warstwie aplikacji i w narzędziach APM, a dla kolejek o alerty age i depth. W testach wymuszaj awarie, aby potwierdzić skuteczność alertów.

Bezpieczeństwo i zgodność

Dane karty powinny być przetwarzane wyłącznie przez bramkę, a Twoja aplikacja otrzymuje token. Dzięki temu ograniczasz zakres zgodności PCI-DSS. W testach zweryfikuj, że nigdzie nie logujesz pełnego numeru karty, CVV ani kodów autoryzacyjnych. Sprawdź politykę retencji i anonimizację danych zgodnie z RODO, także dla testowych kont i zamówień.

Checklista przejścia na produkcję

• Wszystkie zmienne środowiskowe wskazują na produkcję, a klucze testowe są usunięte.
• Adresy webhooków zaktualizowane na produkcyjne, test podpisów pozytywny.
• Feature flag test_mode wyłączony w prod, pozostaje tylko narzędzie developerskie na dev/stage.
• Testy E2E zielone w ostatnim buildzie, scenariusze wysokiego ryzyka przeszły.
• Plan awaryjny i runbook dla incydentów, w tym manualne rozliczenia i komunikacja.

Przykładowa implementacja przełącznika środowiska

W warstwie konfiguracji:

• PAYMENT_MODE=test lub prod steruje wyborem endpointów, kluczy i polityki logowania.
• Dodatkowa flaga FORCE_FAULTY_GATEWAY w stage umożliwia wymuszenie błędów do testów odporności.
• W UI odczytuj tryb i wyświetlaj dyskretny znacznik, że użytkownik jest w środowisku testowym.

W warstwie backendu:

• Adapter PaymentGateway wybiera implementację Stripe/PayU/Przelewy24 w zależności od konfiguracji.
• Każde wywołanie opatrz idempotency key oraz correlation id do śledzenia w logach.
• Waliduj odpowiedzi i mapuj statusy bramki na statusy domenowe zamówienia.

Najczęstsze pułapki i jak ich uniknąć

• Mieszanie kluczy środowisk — separuj projekty i używaj sekretów per środowisko.
• Brak testów asynchronicznych — bez webhooki rekonsyliacja będzie niepełna.
• Nieużywanie idempotencji — ryzyko podwójnych obciążeń przy retry.
• Przetwarzanie PAN na serwerze — stosuj tokenizacja po stronie bramki.
• Nieuwzględnienie strefy SCA — testuj 3‑D Secure i wyjątki.

Dokumentacja operacyjna i szkolenia

Opracuj runbook dla działu wsparcia: jak sprawdzić status w bramce, jak ręcznie wykonać zwrot, jak odczytać eventy, jak przeprowadzić test w środowisku stage. Zamieść przykłady zapytań do API, mapę kodów błędów oraz ścieżki eskalacji. Materiał ten powinien być aktualizowany wraz ze zmianami w platformie płatniczej.

Rozszerzone scenariusze i testy brzegowe

Rozważ dodatkowe scenariusze:

• Zmiana waluty w trakcie checkoutu i walidacja kursu.
• Raty i płatności odroczone, w tym odmowy po analizie ryzyka.
• Wielokrotne próby w krótkim czasie i blokady antyfraudowe.
• Przeciążenie kolejki webhooków oraz mechanizm backpressure.
• Integracja z programem lojalnościowym i prawidłowe księgowanie punktów w razie zwrotu.

Pamiętaj o dokumentowaniu wyników — matryca pokrycia testami pomoże dowieść gotowości do produkcji.

Komunikacja z klientem w trybie testowym

W środowisku testowym oznacz interfejs w sposób czytelny, aby uniknąć nieporozumień. Wysyłaj maile i powiadomienia na testowe skrzynki, taguj transakcje niemożliwe do rozliczenia w realnym świecie. Zadbaj o to, aby żaden z komunikatów nie sugerował rzeczywistego obciążenia konta klienta.