VOXIBLY
← Powrót do funkcji

Integracja bramki płatności Stripe z checkoutem (Projekt Aurora)

Z mówionego zlecenia uporządkowany brief gotowy do przekazania.

Przykład rzeczywistego wyniku

Podsumowanie

Marek z zespołu Płatności podyktował brief na podłączenie bramki płatności Stripe do checkoutu sklepu Projekt Aurora. Celem jest zastąpienie obecnego ręcznego fakturowania płatnościami kartą online, z obsługą Apple Pay i Google Pay. Termin wdrożenia produkcyjnego to 15 lipca, a MVP na środowisku testowym do końca czerwca.

Szczegółowy protokół

Co trzeba zbudować

Celem jest dodanie do istniejącego checkoutu Projektu Aurora płatności kartą przez Stripe. Po wypełnieniu koszyka klient wybiera sposób płatności i płaci bezpośrednio na stronie, bez przekierowania do zewnętrznej bramki. Marek podkreślił, że formularz płatności ma być osadzony przez Stripe Elements, żeby pozostał w designie sklepu.

Oprócz zwykłej karty mają być obsługiwane Apple Pay i Google Pay, ponieważ według analityki zamówienia mobilne stanowią ponad połowę ruchu. Płatność gotówką i na fakturę pozostają jako alternatywy, Stripe to tylko trzecia opcja na dokładkę.

Wymagania techniczne i zabezpieczenia

Kluczowa jest niezawodność potwierdzania płatności. Status zamówienia nie może zmieniać się na podstawie odpowiedzi z przeglądarki, lecz wyłącznie przez webhook Stripe na backendzie (zdarzenie payment_intent.succeeded). Marek wprost ostrzegł przed sytuacją, w której klient płaci, ale połączenie się zrywa i zamówienie zostaje zawieszone jako nieopłacone.

Każde wywołanie musi być idempotentne (ponowne uruchomienie nie założy drugiej płatności) dzięki idempotency key. Webhooki muszą być weryfikowane podpisem, żeby nie dało się ich podrobić. Na wypadek awarii Stripe wymagany jest fallback — checkout nie może całkowicie paść, jedynie ukrywa się karta i oferuje pozostałe sposoby płatności.

Zadania

  • Utworzyć endpoint backendowy do założenia PaymentIntent w Stripe (kwota, waluta, idempotency key). · odpowiada zespół backend · termin do 27 czerwca wysoki
  • Zintegrować Stripe Elements z checkoutem frontendu (karta, Apple Pay, Google Pay) w designie sklepu. · odpowiada zespół frontend · termin do 30 czerwca wysoki
  • Zaimplementować handler webhooków dla payment_intent.succeeded i payment_intent.payment_failed z weryfikacją podpisu. · odpowiada zespół backend · termin do 27 czerwca wysoki
  • Dodać fallback: przy niedostępności Stripe ukryć płatność kartą i zaoferować gotówkę i fakturę. · odpowiada zespół frontend · termin do 3 lipca średni
  • Przygotować scenariusze testowe (sukces, odrzucenie karty, awaria webhooka, zduplikowana płatność) na środowisku testowym. · odpowiada Lucja (QA) · termin do 8 lipca średni

Decyzje

  • Formularz płatności zostanie osadzony przez Stripe Elements bezpośrednio w checkoucie, bez przekierowania na zewnętrzną stronę. 💬 z transkrypcji: „"Chcę to mieć w środku, w tym samym designie, a nie żeby przerzucało człowieka gdzieś na obcą stronę."“
  • Potwierdzenie płatności obsługuje webhook po stronie serwera payment_intent.succeeded, a nie odpowiedź klienta. 💬 z transkrypcji: „"Źródłem prawdy jest webhook na backendzie, kropka."“
  • Apple Pay i Google Pay są częścią pierwszego MVP, a nie późniejszej fazy. 💬 z transkrypcji: „"Apple Pay i Google Pay traktuj jako część podstawy, nie jako bonus na później."“

Kluczowe wnioski

  • Statusem zamówienia steruje wyłącznie webhook po stronie serwera, a nie odpowiedź z przeglądarki — chroni to przed utratą płatności przy zerwanym połączeniu. 💬 z transkrypcji: „"Nigdy, naprawdę nigdy nie potwierdzajcie zamówienia na podstawie tego, co wraca do przeglądarki. Tylko na podstawie webhooka na serwerze."“
  • Zamówienia mobilne stanowią ponad 50% ruchu, dlatego Apple Pay i Google Pay są częścią MVP, a nie drugiej fazy. 💬 z transkrypcji: „"Ponad połowa ludzi kupuje z telefonu, więc Apple Pay i Google Pay muszą być od razu, a nie kiedyś potem."“
  • Przy awarii Stripe nie może paść cały checkout, jedynie ukrywa się płatność kartą i zostają gotówka i faktura. 💬 z transkrypcji: „"Jak Stripe nie zadziała, to niech nie padnie cała kasa. Po prostu chowa się karta i ludzie płacą inaczej."“

Dane

  • 15 lipca data Wdrożenie produkcyjne Termin uruchomienia bramki płatności na produkcji.
  • koniec czerwca data MVP na środowisku testowym Działająca integracja gotowa do testów.
  • wysoki priorytet Priorytet zadania Marek oznaczył płatności kartą jako blokujące dla kampanii letniej.
  • ponad 50 % Udział zamówień mobilnych Powód włączenia Apple Pay i Google Pay do MVP.

Niejasności i ryzyka

  • Nie określono, czy ma być obsługiwane zapisywanie karty do płatności cyklicznych (saved cards), czy tylko płatności jednorazowe.
  • Marek nie wspomniał o konkretnym limicie automatycznego zwrotu środków (refund) — trzeba to dopracować z zespołem wsparcia.
  • Nie padło, w jakich walutach będą realizowane płatności (tylko CZK, czy także EUR dla klientów zagranicznych).

Brief dla wykonawcy

Brief implementacyjny — Integracja bramki płatności Stripe (Projekt Aurora)

Cel

Dodać do istniejącego checkoutu sklepu Projekt Aurora płatność kartą przez Stripe, wraz z Apple Pay i Google Pay, jako trzeci sposób płatności obok gotówki i faktury.

Zakres (scope)

  • Formularz płatności osadzony przez Stripe Elements bezpośrednio w checkoucie (bez przekierowania do zewnętrznej bramki).
  • Obsługa metod płatności: karta, Apple Pay, Google Pay.
  • Potwierdzanie płatności po stronie serwera przez webhooki (źródło prawdy = backend, nie przeglądarka).
  • Fallback przy niedostępności Stripe (degradacja bez padu całego checkoutu).

Poza zakresem (out of scope)

  • Zapisywanie kart do płatności cyklicznych (saved cards) — na razie nie realizujemy, czeka na decyzję.
  • Zwroty przez UI administracji — dla MVP wystarczy zwrot przez Stripe Dashboard.

Wymagania funkcjonalne

  1. Założenie płatności
    • Endpoint backendowy tworzy PaymentIntent (kwota, waluta, idempotency_key).
    • Frontend pobiera client_secret i renderuje Stripe Elements.
  2. Potwierdzenie płatności
    • Status zamówienia zmienia wyłącznie webhook payment_intent.succeeded.
    • Odpowiedź klienta służy tylko do wyświetlenia ekranu „dziękujemy", nigdy do potwierdzenia zamówienia.
  3. Niepowodzenie płatności
    • Webhook payment_intent.payment_failed → zamówienie zostaje w stanie „oczekuje na płatność", klient dostaje możliwość ponowienia próby.
  4. Fallback
    • Przy niedostępności Stripe płatność kartą jest ukrywana i pokazują się gotówka + faktura. Checkout nie może paść w całości.

Wymagania niefunkcjonalne

  • Idempotencja: każde wywołanie PaymentIntent używa idempotency key (ponowne wysłanie nie założy drugiej płatności).
  • Bezpieczeństwo webhooków: weryfikacja podpisu (Stripe-Signature), odrzucenie niezweryfikowanych żądań.
  • Secrets: klucze API Stripe wyłącznie w GCP Secret Manager, nigdy w kodzie ani w pliku .env w gicie.
  • Logowanie: każde niepowodzenie płatności i każdy przychodzący webhook do structured logging (Cloud Logging).

Kryteria akceptacji

  • Klient płaci kartą i zamówienie zostaje oznaczone jako opłacone dopiero po otrzymaniu webhooka payment_intent.succeeded.
  • Apple Pay i Google Pay pojawiają się na obsługiwanych urządzeniach i działają end-to-end.
  • Przy zerwanym połączeniu po zapłacie (zamknięta przeglądarka) zamówienie i tak jest oznaczone jako opłacone dzięki webhookowi.
  • Podwójne wysłanie płatności nie zakłada dwóch płatności (zweryfikowane idempotency key).
  • Podrobiony webhook bez ważnego podpisu jest odrzucany (HTTP 400).
  • Przy symulowanej awarii Stripe checkout się nie psuje, jedynie znika płatność kartą.

Terminy

  • MVP na teście: koniec czerwca
  • Produkcja: 15 lipca

Otwarte pytania

  • Zapisywanie kart do płatności cyklicznych — tak/nie?
  • Waluty: tylko CZK, czy także EUR?
  • Limit automatycznego zwrotu?

Przykład transkrypcji

Marek (zlecający)

No to bierzemy się za płatności. Chcę, żebyśmy do checkoutu na Aurorze w końcu wprowadzili płatność kartą przez Stripe. Teraz ludzie płacą albo gotówką przy odbiorze, albo na fakturę, i to nas hamuje.

Marek (zlecający)

Ważne, żeby to zostało w środku, w tym samym designie. Żadnego przerzucania na obcą stronę. Osadzimy to przez te ich Elements, żeby wyglądało jak część sklepu.

Marek (zlecający)

A teraz najważniejsze. Nigdy, naprawdę nigdy nie potwierdzajcie zamówienia na podstawie tego, co wraca do przeglądarki. Tylko na podstawie webhooka na serwerze. Mieliśmy już raz tak, że człowiek zapłacił, zerwało mu połączenie i zamówienie wisiało jako nieopłacone. To się nie może powtórzyć.

Marek (zlecający)

Apple Pay i Google Pay traktuj jako część podstawy, nie jako bonus na później. Ponad połowa ludzi kupuje z telefonu, więc to musi być od razu.

Marek (zlecający)

I jeszcze jedna rzecz. Jak Stripe nie zadziała, to niech nie padnie cała kasa. Po prostu chowa się karta i ludzie płacą inaczej. Nie chcę przez awarię bramki stracić całej sprzedaży.

Marek (zlecający)

Docelowo chcę to na produkcji do piętnastego lipca, ze względu na kampanię letnią. Na teście niech działa do końca czerwca, żeby Lucja zdążyła to porządnie przeklikać.

Wypróbuj Voxibly