Express Checkout: Apple Pay, Google Pay i Amazon Pay przez Stripe, kompletny przewodnik

Wprowadzenie

DataFirefly Express Checkout dodaje płatność portfelową, czyli Apple Pay, Google Pay i Amazon Pay, do Twojego sklepu PrestaShop 8 lub 9 za pośrednictwem Stripe. Moduł opiera się na Express Checkout Element od Stripe: jednym komponencie, który automatycznie wykrywa portfele dostępne na urządzeniu klienta i wyświetla odpowiadające im przyciski.

Przyciski mogą pojawiać się w trzech lokalizacjach, włączanych niezależnie: na karcie produktu (zakup ekspresowy), w koszyku i na stronie płatności. Po płatności zamówienie jest tworzone i zatwierdzane przez webhook Stripe z weryfikowanym podpisem, z logiką idempotentną, która wyklucza podwójne zamówienia. Moduł działa w trybie jednego sklepu i multisklep, a tłumaczenia obejmują pięć języków (FR, EN, ES, DE, IT).

Wymagania

• PrestaShop 8.0 do 9.x, PHP 7.4 lub nowszy.
• Aktywne rozszerzenie PHP cURL (sprawdzane przy instalacji).
• Aktywne konto Stripe.
• Sklep serwowany po HTTPS (wymagane przez Apple Pay i Google Pay).

Instalacja

1. W panelu administracyjnym otwórz Moduły > Menedżer modułów.
2. Kliknij Zainstaluj moduł i wskaż archiwum ZIP modułu.
3. Po zakończeniu instalacji kliknij Konfiguruj.

Podczas instalacji moduł tworzy tabelę śledzenia transakcji oraz dedykowany status zamówienia „Płatność autoryzowana (oczekuje na pobranie)”, używany w trybie ręcznego pobrania.

Połączenie ze Stripe

Moduł oferuje dwa tryby połączenia, wybierane w polu Tryb połączenia.

Tryb ręczny (klucze API)

Wpisz swoje klucze z Dashboardu Stripe (Deweloperzy > Klucze API):

• Klucz publiczny i klucz tajny, w wersji testowej, a potem produkcyjnej.
• Sekret webhooka (zobacz sekcję Webhook poniżej).

Na czas wdrożenia ustaw pole Tryb na Test, a na produkcji przełącz na Live. Każdy tryb ma własny zestaw kluczy.

Tryb automatyczny (Stripe Connect / OAuth)

Ten tryb łączy Twoje konto Stripe jednym kliknięciem. Kliknij Połącz ze Stripe, zatwierdź dostęp, a moduł automatycznie pobierze klucz publiczny i tajny, utworzy webhook (wraz z jego sekretem podpisu) i spróbuje zarejestrować domenę wallet dla Apple Pay i Google Pay. Przycisk Rozłącz cofa dostęp i czyści klucze.

Tryb automatyczny wymaga aplikacji Stripe Connect. Są dwie możliwości:

• Własna aplikacja Connect: wpisz client_id oraz sekret platformy (Test i Live).
• Broker DataFirefly: wpisz adres brokera, który przechowuje sekret platformy i przeprowadza wymianę OAuth. Jeśli ten adres jest wypełniony, ma pierwszeństwo.

Konfiguracja Stripe (Dashboard)

Webhook

W trybie ręcznym utwórz punkt końcowy w Deweloperzy > Webhooki > Dodaj endpoint:

• Adres: ten wyświetlany u góry strony konfiguracji modułu (.../module/dfexpresscheckout/webhook).
• Zdarzenia: payment_intent.succeeded i payment_intent.payment_failed.
• Skopiuj sekret podpisu (whsec_…) do konfiguracji modułu.

W trybie automatycznym webhook i jego sekret są tworzone automatycznie podczas łączenia.

Aktywacja portfeli

• Amazon Pay: włącz go w Ustawienia > Metody płatności w swoim Dashboardzie Stripe. Następnie pojawi się automatycznie w Express Checkout Element.
• Apple Pay: Twoja domena musi być zweryfikowana w Stripe (Ustawienia > Apple Pay). W trybie automatycznym moduł próbuje wykonać tę rejestrację za Ciebie.
• Google Pay: aktywny automatycznie, nie wymaga żadnych działań.

Konfiguracja modułu

Lokalizacje wyświetlania

Wyświetlaniem przycisków sterują trzy przełączniki: karta produktu, koszyk i checkout. Włączaj je niezależnie, zgodnie ze swoją strategią.

Tryb pobrania

• Pobranie natychmiastowe (domyślnie): płatność jest pobierana od razu, a zamówienie przechodzi do statusu „Płatność zaakceptowana”.
• Autoryzacja, potem ręczne pobranie: Stripe autoryzuje płatność bez pobierania środków, a zamówienie trafia do statusu „Płatność autoryzowana (oczekuje na pobranie)”.

Nagłówek i motyw

Dostosuj wyświetlany nagłówek nad przyciskami oraz motyw przycisków (czarny, biały, biały z obramowaniem), aby pasowały do Twojego designu.

Po stronie klienta

Zależnie od lokalizacji klient widzi jeden lub kilka przycisków portfela. Potwierdza płatność jedną autoryzacją (Face ID, odcisk palca, hasło Amazon), bez zakładania konta: email oraz adres dostawy i dane rozliczeniowe są pobierane z portfela. Gdy naliczane są koszty wysyłki, moduł proponuje aktywnych przewoźników i przelicza sumę przy każdej zmianie adresu. Produkty cyfrowe działają bez etapu dostawy.

Z poziomu karty produktu zakup ekspresowy dotyczy wyświetlanego produktu (i wybranej ilości) przez dedykowany koszyk, bez naruszania bieżącego koszyka klienta.

Ręczne pobranie: pobierz lub anuluj

W trybie ręcznego pobrania sterowanie odbywa się przez status zamówienia:

• Aby pobrać płatność, ustaw zamówienie na status „Płatność zaakceptowana”.
• Aby zwolnić autoryzację, ustaw zamówienie na status „Anulowane”.

Zamówienia, webhook i idempotentność

Zamówienie jest tworzone i zatwierdzane w momencie odebrania zdarzenia payment_intent.succeeded (podpisany webhook). Kontroler powrotu pełni rolę siatki bezpieczeństwa, gdy klient wraca do sklepu. Tabela transakcji wiąże każdy PaymentIntent z jego zamówieniem: ta sama transakcja nigdy nie generuje dwóch zamówień, niezależnie od kolejności, w jakiej dotrą powrót przeglądarki i webhook. Klient-gość i jego adresy są odtwarzane na podstawie danych zwróconych przez portfel.

Wielojęzyczność i multisklep

Moduł zawiera pliki tłumaczeń FR, EN, ES, DE, IT i działa w kontekście multisklep. Klucze Stripe, tryb połączenia i tryb pobrania są standardowymi ustawieniami konfiguracji.

Rozwiązywanie problemów

Przyciski się nie wyświetlają

Sprawdź, czy sklep działa po HTTPS, czy klucze Stripe są wpisane dla aktywnego trybu (Test/Live) i czy dana lokalizacja jest włączona. Apple Pay pojawia się wyłącznie w Safari/iOS przy zweryfikowanej domenie, a Google Pay w Chrome/Android.

Płatność się udaje, ale zamówienie nie powstaje

Sprawdź webhook: poprawny adres, zdarzenia payment_intent.succeeded i payment_intent.payment_failed oraz sekret podpisu identyczny z tym w module. Przejrzyj logi Stripe (próby dostarczenia webhooka) i logi PrestaShop.

Brak Amazon Pay

Musi zostać włączony w Ustawienia > Metody płatności w Dashboardzie Stripe. Następnie pojawia się automatycznie.

Połączenie automatyczne kończy się błędem

Sprawdź, czy client_id Connect jest wpisany dla aktywnego trybu i czy adres przekierowania modułu został zadeklarowany w Twojej aplikacji Connect. Nieprawidłowy token stanu oznacza wygasłą sesję: uruchom łączenie ponownie z panelu administracyjnego.

Deinstalacja

Deinstalacja usuwa konfigurację modułu. Tabela śledzenia transakcji jest domyślnie zachowywana dla zachowania śladu po złożonych zamówieniach.

FAQ

Czy Amazon Pay naprawdę działa przez Stripe?

Tak. Stripe obsługuje Amazon Pay w ramach Express Checkout Element; wystarczy włączyć go w Dashboardzie Stripe.

Czy trzeba instalować zależności (Composer)?

Nie. Moduł zawiera wbudowanego klienta Stripe w cURL. Wystarczy zainstalować moduł i wpisać (lub połączyć) swoje klucze.

Czy moduł jest zgodny z PrestaShop 9?

Tak, jest zgodny z PrestaShop 8.0 do 9.x i przetestowany na PHP 8.1 do 8.3.

Czy mogę przejść z trybu ręcznego na automatyczny?

Tak, w dowolnym momencie z poziomu konfiguracji. W trybie automatycznym klucze są uzupełniane przez połączenie OAuth, w trybie ręcznym wpisujesz je samodzielnie.