Integracja bramki płatności z PrestaShop może wydawać się prosta na papierze.
Bramka udostępnia dokumentację API, dane uwierzytelniające do środowiska testowego, klucze uwierzytelniania, adresy URL wywołania zwrotnego oraz kilka punktów końcowych. Następnie moduł PrestaShop wysyła żądanie płatności, odbiera odpowiedź, tworzy zamówienie i przekierowuje klienta na stronę potwierdzenia.
W prawdziwym sklepie PrestaShop bramka płatności rzadko działa jednak sama.
W momencie, gdy sklep korzysta z modułu One Page Checkout (OPC), takiego jak SuperCheckout, wiele modułów płatności, niestandardowe przepływy płatności, ramki iframe, metody płatności oparte na JavaScript i dodatkowe dostosowania procesu realizacji transakcji mogą ze sobą współdziałać.
W tym miejscu integracja wielu płatności staje się trudna.
Podczas prac nad kompatybilnością bramki płatniczej napotkaliśmy przypadki, w których metoda płatności działała idealnie w domyślnym koszyku PrestaShop, ale zachowywała się inaczej w OPC. Na przykład, dostawca płatności mógł wyświetlać się poprawnie w standardowym koszyku, podczas gdy opcje takie jak BLIK, wybór banku czy BNPL znikały w SuperCheckout.
Ważną lekcją było to, że integracja bramki płatności to nie tylko sprawne wywołanie API. Chodzi o to, aby cały cykl płatności działał poprawnie w kasie PrestaShop.
1.0 Czego właściwie potrzebuje niestandardowa bramka płatności?
Ogólnie rzecz biorąc, integracja płatności PrestaShop musi obsługiwać pięć rzeczy:
- Wyświetl metodę płatności przy kasie.
- Wyślij dane klienta lub płatności do bramki płatniczej.
- Odbierz i zatwierdź odpowiedź bramy.
- Utwórz lub zaktualizuj poprawnie zamówienie PrestaShop.
- Przekieruj klienta do odpowiedniej strony potwierdzenia lub błędu.
Typowy moduł płatności rozszerza klasę nie tylko bazową.
Moduł płatności zazwyczaj współpracuje z takimi haczykami jak:
Haczyk odpowiada za udostępnienie metody płatności przy kasie.
Haczyk obsługuje to, co widzi klient po zakończeniu procesu płatności.
Na przykład:
publiczna funkcja hookPaymentOptions($params) { if (!$this->active || !$this->checkCurrency($params['cart'])) { return []; } $paymentOption = new PaymentOption(); $paymentOption ->setCallToActionText($this->l('Płać kartą')) ->setAction( $this->context->link->getModuleLink( $this->name, 'redirect', [], true ) ); return [$paymentOption]; }
Ważne jest, aby ten haczyk nie zakładał po prostu, że metoda płatności zawsze będzie widoczna.
Na decyzję o wyświetleniu metody płatności wpływają waluta, kraj, operator, stan klienta, wartość koszyka, konfiguracja modułu i dostępność bramki płatniczej.
2.0 Część, która zmienia wszystko: OPC
Domyślna platforma PrestaShop i moduł OPC niekoniecznie przetwarzają metody płatności w dokładnie ten sam sposób.
Była to jedna z najważniejszych lekcji, jakie wyniosłem z pracy z wieloma modułami płatności.
W przypadku domyślnego procesu płatności moduł płatności zazwyczaj sam kontroluje renderowanie opcji płatności i przebieg płatności.
Dzięki OPC moduł płatności staje się kolejną warstwą pomiędzy modułem płatności a klientem. Oznacza to, że mogą na siebie oddziaływać następujące elementy:
Klient ↓ OPC / SuperCheckout ↓ Opcje płatności ↓ Moduł płatności ↓ Interfejs API bramy ↓ Odpowiedź bramy ↓ Moduł płatności ↓ OPC / PrestaShop ↓ Potwierdzenie zamówienia
Moduł płatności może zatem być całkowicie poprawny z punktu widzenia interfejsu API, a mimo to zachowywać się nieprawidłowo w ramach OPC.
Dlatego testy zgodności płatności powinny zawsze obejmować:
- Domyślna kasa PrestaShop
- Rzeczywisty OPC używany przez sklep
Testowanie wyłącznie domyślnego sposobu realizacji transakcji może dać fałszywe wrażenie, że integracja została ukończona.
3.0 Przykład z życia wzięty: brak opcji PayU w OPC
Jednym z problemów praktycznych, na jakie natrafiliśmy, były opcje płatności PayU.
W standardowym procesie płatności PrestaShop, PayU poprawnie wyświetlało dostępne metody płatności. Jednak w SuperCheckout brakowało niektórych opcji płatności.
Na przykład, w zależności od konfiguracji i koszyka:
- BLIK nie był stale widoczny.
- Lista wyboru banków nie rozwinęła się prawidłowo.
- Brakowało niektórych wierszy BNPL/płatności.
- W niektórych przypadkach BLIK pojawiał się, a potem znikał.
Na pierwszy rzut oka wyglądało to na problem z API PayU. Ale nim nie było.
Ważnym krokiem diagnostycznym było porównanie przepływu płatności między domyślną kasą i SuperCheckout.
Jeśli ten sam moduł płatności działa przy domyślnym kasie, ale zawodzi w OPC, dochodzenie powinno objąć więcej niż tylko interfejs API bramki płatniczej.
Musimy sprawdzić, w jaki sposób OPC tworzy metody płatności i jakie informacje przekazuje do modułów płatności.
4.0 Kwota płatności może mieć wpływ na widoczność metody płatności
Szczególnie ważnym elementem tego badania była kwota w koszyku. Bramki płatnicze często mają minimalne i maksymalne limity transakcji. Na przykład:
Metoda płatności ↓ Sprawdź kwotę w koszyku ↓ Minimalna kwota? Maksymalna kwota? ↓ Uprawniony / Nieuprawniony
Podczas badania zgodności z PayU prześledziliśmy logikę filtrowania metody płatności, aby ustalić, jaka kwota w koszyku jest przekazywana podczas kontroli metody płatności.
Odpowiedni przepływ obejmował obliczenia koszyka PrestaShop i filtrowanie metody płatności, w tym logikę obejmującą:
Koszyk::OBA
i:
PayMethodsCache::checkMinMax
Ma to znaczenie, ponieważ opcja płatności może zniknąć z procesu płatności, a interfejs API nie zwróci błędu.
Bramka może po prostu zostać uznana za niekwalifikującą się do otrzymania kwoty przez moduł płatności. To daje nam ważną regułę debugowania:
Jeśli opcja płatności zniknie z OPC, nie zakładaj od razu, że API płatności jest uszkodzone. Najpierw sprawdź kwotę koszyka, walutę, minimalne/maksymalne limity oraz wartości osiągające kwalifikowalność metody płatności.
Staje się to jeszcze ważniejsze, gdy w grę wchodzą zniżki, koszty wysyłki, podatki, vouchery lub niestandardowe kalkulacje płatności.
5.0 Dlaczego metody płatności działają w domyślnej kasie, ale nie działają w SuperCheckout
Przydatnym sposobem zbadania tych problemów jest porównanie dwóch środowisk realizacji transakcji.
5.1 Domyślna kasa PrestaShop
Koszyk ↓ FinderOpcjiPłatności ↓ haki paymentOptions ↓ Moduły płatności ↓ Opcje płatności
5.2 Wymeldowanie OPC
Koszyk ↓ SuperKasa ↓ Metody Płatności ↓ Moduły płatności ↓ Dodatkowe przetwarzanie OPC ↓ Wyrenderowany interfejs użytkownika płatności
Drugi przepływ ma dodatkowe ruchome części.
Dlatego podczas debugowania problemu z płatnością nie sprawdzamy tylko: „Czy moduł płatności działa?”
Sprawdzamy: „Czy moduł płatności działa, gdy jego dane wyjściowe są przetwarzane i renderowane przez tę konkretną implementację kasy?”
Dzięki temu rozróżnieniu zaoszczędzono sporo czasu podczas debugowania.
6.0 PaymentOption to tylko część integracji
Począwszy od PrestaShop 1.7, moduły płatności zazwyczaj wykorzystują kod HTML do wyprowadzania płatności za pomocą starszej metody płatności.
Opcja płatności może zawierać informacje takie jak:
$paymentOption ->setCallToActionText(...) ->ustawAkcję(...) ->ustawWejścia(...) ->ustawDodatkoweInformacje(...)
obiektów zamiast bezpośrednio
Różne bramki wymagają różnych kombinacji.
6.1 Brama oparta na przekierowaniu
Klient klika metodę płatności i zostaje przekierowany do bramki płatniczej.
Zamówienie ↓ Opcja płatności ↓ Kontroler modułu ↓ Bramka
6.2 Wbudowany formularz płatności
Pola płatności wyświetlane są bezpośrednio w kasie.
Zamówienie ↓ Opcja płatności ↓ Formularz karty/płatności ↓ Interfejs API bramy
6.3 Płatność oparta na ramkach iframe
Interfejs bramki płatniczej jest osadzony w kasie.
Zamówienie ↓ Opcja płatności ↓ Iframe ↓ Bramka
Ostatnie dwa podejścia wymagają szczególnej uwagi, ponieważ JavaScript, manipulacja DOM, ładowanie ramek iframe i odświeżanie OPC mogą mieć wpływ na interfejs płatności.
7.0 JavaScript staje się krytyczny w przypadku OPC
To jest obszar, który często pomijany jest w ogólnych poradnikach dotyczących integracji płatności.
OPC może dynamicznie odświeżać części procesu realizacji transakcji w przypadku zmiany klienta:
- adres dostawy
- kraj
- nośnik
- metoda płatności
- informacje rozliczeniowe
- Sposób wysyłki
Kiedy tak się stanie, kod HTML dotyczący płatności może zostać zastąpiony.
Zdarzenie JavaScript, które działało podczas początkowego ładowania strony, może przestać działać po odświeżeniu AJAX.
Na przykład:
Początkowe obciążenie kasy ↓ Zainicjowano płatność JS ↓ Klient zmienia dane dotyczące płatności/wysyłki ↓ OPC odświeża sekcję płatności ↓ Oryginalny DOM zastąpiony ↓ Płatność JS nie jest już dołączona
Może to powodować niejasne objawy.
Metoda płatności może pojawić się początkowo, ale kliknięcie jej nic nie da. Ramka iframe może zniknąć.
Lista banków może przestać się rozszerzać.
Opcja płatności może pojawiać się i znikać po zmianie innego pola płatności.
Dlatego też prace nad zapewnieniem kompatybilności często wymagają zmian nie tylko w PHP, ale także w JavaScript modułu płatności.
8.0 Prawdziwy przykład: SimplyLease + SuperCheckout
Inny przykład dotyczył integracji SimplyLease z SuperCheckout. Problem nie ograniczał się do API bramki.
Niektóre elementy informacji i kalkulatora SimplyLease były częścią prezentacji płatności i musiały poprawnie działać w ramach procesu SuperCheckout.
Zmiany w zakresie kompatybilności dotyczyły zarówno szablonów modułów, jak i integracji JavaScript po stronie SuperCheckout. Wśród plików znalazły się:
moduły/simplylease/widoki/szablony/hook/payment_info.tpl moduły/simplylease/widoki/szablony/hook/product_calculator.tpl moduły/supercheckout/kontrolery/front/SupercheckoutCore.php moduły/supercheckout/widoki/js/front/supercheckout.js moduły/supercheckout/widoki/js/front/simplylease_supercheckout.js
To dobry przykład, dlaczego zapewnienie kompatybilności płatności czasami wymaga wprowadzenia zmian poza samym modułem bramki płatniczej.
Dostawca płatności może udostępnić prawidłowe dane, ale proces realizacji płatności nadal musi:
- Wyrenderuj to.
- Zachowaj je podczas odświeżania transakcji.
- Zainicjuj wymagany JavaScript.
- Zachowaj synchronizację informacji o płatnościach z bieżącym koszykiem.
9.0 Inny częsty problem: brak metody płatności
Spotkaliśmy się również z przypadkami, gdy metoda płatności, np. Comfino, nie pojawiała się w SuperCheckout, mimo że sam moduł płatności był zainstalowany i skonfigurowany.
Tego typu kwestie należy badać systematycznie.
Czek:
9.1 Czy moduł jest aktywny?
$this->active
9.2 Czy waluta jest obsługiwana?
$this->checkCurrency($params['koszyk'])
9.3 Czy kraj jest obsługiwany?
Niektóre bramki płatnicze ograniczają metody płatności w zależności od kraju klienta.
9.4 Czy łączna wartość koszyka mieści się w limitach bramki płatniczej?
Minimalna i maksymalna wartość transakcji może uniemożliwić wyświetlenie metody.
9.5 Czy operator jest obsługiwany?
Niektóre moduły płatności ograniczają metody płatności w zależności od przewoźnika.
9.6 Czy filtrowanie OPC jest metodą?
Moduł płatności może zwracać prawidłowe metody, które są gromadzone, filtrowane lub renderowane. Jednak OPC nadal może modyfikować sposób płatności
9.7 Czy JavaScript ukrywa lub zastępuje element?
Metoda płatności może teoretycznie zostać zwrócona przez PHP, ale nadal nie będzie widoczna w końcowym etapie płatności.
Dlatego narzędzia programistyczne przeglądarek są tak samo ważne jak logi PHP podczas debugowania integracji płatności.
10.0 haczyków, na które naprawdę musimy zwrócić uwagę
Niestandardowej integracji płatności nie należy traktować jako implementacji pojedynczego haka.
Dokładne haki zależą od architektury bramki i kasy, ale niektóre są szczególnie ważne.
10.1 Opcje płatności
To jest podstawowy sposób ujawnienia metody płatności podczas realizacji transakcji.
Jest odpowiedzialny za powrót opcje płatności obiekty.
Typowe kontrole obejmują:
jeśli (!$this->active) { return [];
}
jeśli (!$this->checkCurrency($params['cart'])) { return [];
}
Następnie można zastosować dodatkowe ograniczenia specyficzne dla bramy.
10.2 Zwroty płatności
Jest to używane po zakończeniu lub powrocie klienta z procesu płatności. Może wyświetlać:
- numer referencyjny zamówienia
- status płatności
- dodatkowe instrukcje dotyczące płatności
- informacje specyficzne dla bramy
10.3 actionPresentPaymentOptions
Ten wątek staje się szczególnie interesujący, gdy w grę wchodzi wiele modułów płatności i OPC.
Działa na podstawie zgromadzonych opcji płatności i może okazać się przydatny, gdy kasjer musi sprawdzić lub zmodyfikować całą kolekcję opcji płatności.
Różni się to od wdrażania opcji płatności pojedynczej bramki hak.
Ważne jest to rozróżnienie:
opcje płatności ↓ Każdy moduł płatności wnosi swoją opcję actionPresentPaymentOptions ↓ Złożone opcje płatności mogą zostać przetworzone
Podczas debugowania zgodności OPC zrozumienie, gdzie pobierane są opcje płatności, a gdzie są one ostatecznie prezentowane, może decydować o tym, czy problem zostanie szybko rozwiązany, czy trzeba będzie spędzić wiele godzin w module bramki.
11.0 Tworzenie zamówień: Nigdy nie ufaj przeglądarce
Gdy płatność dotrze do bramki, kolejnym kluczowym krokiem jest utworzenie zamówienia. Najważniejszą metodą PrestaShop jest tutaj:
walidujZamówienie()
Uproszczony przykład:
$this->module->validateOrder(
$cart->id, Konfiguracja::get('PS_OS_PAYMENT'),
$amountPaid,
Metoda płatności,
wiadomość, [],
null, false,
$customer->secure_key
);
Na szczególną uwagę zasługują trzy wartości:
11.1 Identyfikator koszyka
Koszyk musi należeć do oczekiwanego klienta/oczekiwanej sesji i musi być ważny.
11.2 Kwota płatności
Nie stosuj bezmyślnie:
$cart->getOrderTotal()
jako dowód, że bramka otrzymała tę kwotę.
Kwota powinna zostać zweryfikowana na podstawie odpowiedzi bramki.
11.3 Klucz bezpieczny
Klient musi być prawidłowo powiązany z koszykiem/przepływem zamówień.
12.0 Webhooki muszą być idempotentne
Bramka płatności może wysłać ten sam webhook więcej niż raz. Na przykład:
Bramka ↓ webhook ↓ Twój serwer ↓ Odpowiedź 200
Jeżeli odpowiedź zostanie utracona:
Bramka ↓ webhook ↓ Twój serwer ↓ Odpowiedź utracona ↓ Ponowne próby bramy
Jeśli integracja tworzy zamówienie za każdym razem, gdy otrzymuje webhook, możliwe jest duplikowanie zamówień. Dlatego wywołanie zwrotne powinno sprawdzić, czy koszyk zawiera już zamówienie, przed utworzeniem kolejnego. Koncepcyjnie:
jeśli ($cart->OrderExists()) {
// Już przetworzone
// Zwróć pomyślną odpowiedź
}
Obsługę webhooków należy zaplanować w taki sposób, aby umożliwić bezpieczne przetwarzanie powtarzających się powiadomień.
13.0 Płatności synchroniczne i asynchroniczne
Nie każda bramka płatnicza potwierdza płatność od razu.
13.1 Synchroniczne
Bramka natychmiast potwierdza transakcję.
Klient ↓ Bramka ↓ Płatność zatwierdzona ↓ walidujZamówienie() ↓ PŁATNOŚĆ PS_OS ↓ Potwierdzenie
13.2 Asynchroniczny
Klient może dokonać zwrotu przed otrzymaniem ostatecznego potwierdzenia płatności.
Klient ↓ Bramka ↓ Wróć do sklepu ↓ Oczekujące zamówienie ↓ webhook ↓ Zweryfikuj płatność ↓ Zmień stan zamówienia ↓ Płatność zaakceptowana
W przypadku bramek asynchronicznych korzystanie z dedykowanego stanu zamówienia oczekującego jest często bezpieczniejsze niż natychmiastowe oznaczenie zamówienia jako opłacone.
Po potwierdzeniu płatności przez webhook:
$history = nowa HistoriaZamówień();
$history->id_order = (int) $order->id;
$history->changeIdOrderState( Konfiguracja::get('PS_OS_PAYMENT'),
Zamówienie
);
$history->addWithemail(true);
Dzięki temu zmiana stanu zamówienia odbywa się za pośrednictwem mechanizmu historii zamówień PrestaShop, a nie po prostu poprzez zmianę wartości w bazie danych.
14.0 Jedna z najprzydatniejszych technik debugowania: porównanie przepływów realizacji transakcji
Jeśli metoda płatności działa w domyślnym punkcie realizacji transakcji, ale nie w OPC, zalecamy porównanie całego procesu.
Krok 1: Sprawdź PHP
Czy hookPaymentOptions() wykonany?
Krok 2: Sprawdź zwrócone opcje
Czy moduł płatności faktycznie zwraca opcja płatności?
Krok 3: Sprawdź koszyk
Porównać:
- całkowity
- waluta
- klient
- kraj
- nośnik
- rabaty
- podatki
- żegluga
Krok 4: Sprawdź przeglądarkę
Szukać:
- Błędy JavaScript
- brakujące elementy DOM
- Żądania AJAX
- nieudane żądania
- błędy iframe
Krok 5: Sprawdź OPC
Określ, czy SuperCheckout jest:
- filtrowanie opcji płatności
- zastąpienie jego kodu HTML
- odświeżanie sekcji płatności
- zmiana koszyka przed uruchomieniem modułu płatności
Krok 6: Sprawdź bramę
Dopiero po potwierdzeniu lokalnego przepływu płatności można rozpocząć dochodzenie w celu dokładniejszego sprawdzenia:
- Uwierzytelnianie API
- żądanie ładunku
- podpis
- odpowiedź
- hak sieciowy
- dzienniki bramy
To podejście wielowarstwowe jest o wiele szybsze niż każdorazowe zaczynanie od interfejsu API bramy.
15.0 Typowe problemy z integracją płatności, które zaobserwowaliśmy
Prace nad zapewnieniem zgodności ze standardami rzeczywistymi zwykle ujawniają problemy, które nie są oczywiste w dokumentacji bramy.
15.1 Opcja płatności znika
Możliwe przyczyny:
- nieobsługiwana waluta
- ograniczenie kraju
- kwota w koszyku poza limitami bramki
- ograniczenie przewoźnika
- Filtrowanie OPC
- konfiguracja modułu płatności
- JavaScript ukrywa metodę
15.2 BLIK lub inna opcja płatności pojawia się i znika
Możliwe przyczyny:
- sprawdź odświeżenie AJAX
- ponowne renderowanie opcji płatności
- Inicjalizacja JavaScript
- całkowita suma koszyka ulega zmianie
- kwalifikowalność do bramki jest przeliczana
15.3 Lista banków nie rozszerza się
Często badaj:
- Błędy JavaScript
- dynamicznie zastępowane elementy DOM
- obsługi zdarzeń dołączone przed odświeżeniem OPC
- inicjalizacja JavaScript dostawcy płatności
15.4 Iframe znika
Zbadać:
- odświeżenie kasy
- inicjalizacja iframe
- Zastąpienie DOM
- Wykonywanie JavaScript po aktualizacjach AJAX
15.5 Płatność powiodła się, ale zamówienie pozostaje w toku
Czek:
- adres URL webhooka
- dostarczanie webhooków
- weryfikacja podpisu
- wyszukiwanie koszyka/zamówienia
- przejście między stanami zamówienia
- uwierzytelnianie zwrotne
15.6 Metoda płatności działa w domyślnym kasie, ale nie OPC
Jest to mocny sygnał, że problem może dotyczyć interakcji między modułem płatności i OPC, a nie samego interfejsu API bramki płatniczej.
16.0 Wymagania bezpieczeństwa dla modułu płatności
Moduły płatności obsługują wrażliwe operacje, więc bezpieczeństwo nie może być traktowane jako opcjonalne ulepszenie. Minimum:
- Sprawdź poprawność podpisów wywołań zwrotnych.
- Sprawdź powiązanie koszyka z klientem.
- Użyj protokołu HTTPS.
- Sprawdź poprawność certyfikatów TLS.
- Nigdy nie ufaj statusowi płatności podawanemu wyłącznie przez przeglądarkę.
- Nigdy nie przechowuj surowych informacji o kartach, chyba że architektura i wymagania dotyczące zgodności wyraźnie to uzasadniają.
- Nie rejestruj poufnych informacji dotyczących płatności.
-
Unikaj serialize() i unserialize() / dla niezaufanych danych zewnętrznych. - Sprawdź poprawność i rzutowanie wartości przychodzących.
- Chroń niestandardowe punkty końcowe AJAX i wywołania zwrotne.
- W razie potrzeby używaj bezpiecznych tokenów.
- Ustaw przetwarzanie webhooków jako idempotentne.
Strona informująca o pomyślnej płatności nie stanowi dowodu dokonania płatności.
O tym, czy zamówienie zostanie uznane za opłacone, powinna decydować zweryfikowana odpowiedź serwera bramki płatniczej.
17.0 Jakie zmiany nastąpią przy obsłudze wielu modułów płatności?
Inną lekcją, jaką można wyciągnąć z prac nad zgodnością z OPC, jest to, że dodanie drugiego lub trzeciego modułu płatności może ujawnić problemy, które nie były widoczne, gdy istniała tylko jedna metoda płatności.
Na przykład:
PayPal PayU Comfino SimplyLease iDeal
Wszystkie mogą mieć przypisane opcje płatności do tej samej płatności. W związku z tym płatność musi uwzględniać różne:
- Struktury HTML
- JAVASCRIPT
- wymagania dotyczące ramek iframe
- przekierowania
- Przepływy API
- zasady kwalifikowalności
- minimalne/maksymalne kwoty
- asynchroniczne wywołania zwrotne
Zmiana wprowadzona dla jednej metody płatności może przypadkowo wpłynąć na inną. Dlatego poprawki dotyczące kompatybilności płatności powinny mieć wąski zakres.
Na przykład zamiast zmieniać globalnie całą logikę przetwarzania opcji płatności, zidentyfikuj konkretną metodę płatności i zastosuj obsługę zgodności tylko tam, gdzie jest to wymagane.
18.0 Testowanie powinno obejmować rzeczywiste scenariusze koszyków
Testowanie bramki płatniczej z prostym produktem o wartości 10 € to za mało. Prawidłowa matryca testowa powinna zawierać:
| Scenariusz | Co zweryfikować |
| Pojedynczy produkt | Pojawia się opcja płatności |
| Wiele produktów | Prawidłowa kwota dociera do bramki |
| Zniżka | Ostateczna kwota do zapłaty jest prawidłowa |
| Opłata transportowa | Bramka otrzymuje prawidłową sumę |
| Podatek | Kwota bramki pasuje do zamówienia |
| Minimalna kwota bramki | Metoda pojawia się/znika poprawnie |
| Maksymalna kwota bramki | Metoda pojawia się/znika poprawnie |
| Nieobsługiwana waluta | Metoda jest ukryta |
| Nieobsługiwany kraj | Metoda jest ukryta |
| Domyślne zamówienie | Płatności działają |
| OPC | Płatności działają |
| Kasa mobilna | Interfejs użytkownika działa |
| Nieudana płatność | Prawidłowy stan zamówienia/płatności |
| Pomyślna płatność | Zamówienie zostało utworzone poprawnie |
| Ponowna próba webhooka | Brak duplikatów zamówień |
| Porzucenie klienta | Brak błędnie opłaconego zamówienia |
| Przekroczono limit czasu bramy | Popraw obsługę oczekujących/błędów |
W przypadku integracji OPC należy również przetestować odświeżanie checkoutu. Zmień:
- adres
- nośnik
- kraj
- metoda płatności
- ilość
- rabat
i sprawdź, czy opcje płatności są prawidłowe po każdym odświeżeniu.
19.0 Praktyczne podejście do rozwoju
Biorąc pod uwagę problemy, które często pojawiają się w rzeczywistych integracjach, najbezpieczniejsza kolejność rozwoju wygląda następująco:
19.1 Spraw, aby bramka działała z domyślną płatnością PrestaShop
Najpierw ustal, że:
Opcja płatności ↓ Żądanie bramki ↓ Odpowiedź bramy ↓ walidujZamówienie() ↓ Potwierdzenie
działa prawidłowo.
19.2 Dodaj przetwarzanie wywołania zwrotnego/webhooka
Nie pozostawiaj asynchronicznego potwierdzenia na koniec.
19.3 Dodaj odpowiednią obsługę stanu zamówienia
Test:
- sukces
- brak
- w oczekiwaniu
- Timeout
19.4 Test z realistycznymi wózkami
Użyj rabatów, kosztów wysyłki, podatków, różnych walut i różnych sum.
19.5 Integracja z OPC
Dopiero gdy podstawowy przepływ danych będzie stabilny, można sprawdzić kompatybilność z SuperCheckout.
19.6 Testowanie JavaScript i dynamiczne odświeżanie
Jest to szczególnie istotne w przypadku osadzonych formularzy płatności, ramek iframe, interfejsów BLIK/wyboru banku i innych interaktywnych komponentów płatności.
19.7 Przetestuj wszystkie metody płatności razem
Kasę obsługującą pięć metod płatności należy testować jako system, a nie jako pięć oddzielnych modułów.
20.0 Czy powinieneś zbudować niestandardową bramkę czy wykorzystać istniejący moduł?
Nie każda brama sieciowa uzasadnia niestandardową integrację. Niestandardowy moduł ma sens, gdy:
- brama jest regionalna lub niszowa
- nie ma utrzymywanego modułu PrestaShop
- brama wymaga niestandardowej logiki biznesowej
- potrzebujesz konkretnego procesu subskrypcji lub rozliczeń
- potrzebujesz funkcjonalności, której istniejące moduły nie mogą zapewnić
Ale zbudowanie integracji płatności oznacza również przyjęcie odpowiedzialności za jej utrzymanie. Zmiany w PrestaShop.
Zmiany w PHP. Zmiany w API bramek.
Zmieniają się wymagania bezpieczeństwa. Zmieniają się moduły płatności.
A ostatecznie dostawca płatności wprowadza zmiany, które zakłócają stabilną integrację.
W przypadku popularnych bramek płatniczych posiadanie i utrzymywanie odpowiedniego modułu może okazać się znacznie tańsze niż utrzymywanie przez kilka lat własnego kodu płatności.
21.0 Większa lekcja z integracji płatności PrestaShop
Najważniejszą lekcją płynącą z pracy z bramkami płatniczymi jest to, że API często nie jest najtrudniejszą częścią. Wysyłanie:
Żądanie API → Odpowiedź API
jest zazwyczaj proste.
Najtrudniejszą częścią jest wszystko, co ją otacza:
┌── Zasady walutowe ├── Zasady obowiązujące w danym kraju ├── Kwota koszyka ├── Ograniczenia operatora ├── OPC ├── JAVASCRIPT ├── IFrame ├── Odświeżanie AJAX ├── webhook ├── Stany zamówienia └── Duplikaty powiadomień ↓ Klient → Zamówienie → Moduł Płatności → Bramka ↓ Tworzenie zamówienia ↓ Potwierdzenie zamówienia
Integracja płatności powiedzie się tylko wtedy, gdy cały łańcuch zachowuje się spójnie.
Dlatego też problemów takich jak „Brak BLIKA” lub „lista banków się nie otwiera” nie należy od razu traktować jako problemu związanego z bramką API.
Rzeczywistą przyczyną może być obliczenie wartości koszyka, sprawdzenie kwalifikowalności metody płatności, renderowanie OPC, inicjalizacja JavaScript lub odświeżenie AJAX zastępujące interfejs płatności.
22.0 Ostateczna lista kontrolna dla niestandardowej bramki płatności PrestaShop
Przed uznaniem integracji za zakończoną należy sprawdzić:
- Moduł płatności rozszerza się Moduł płatności.
- opcje płatności jest zaimplementowany poprawnie.
- Zwrot płatności jest wdrażany tam, gdzie jest to wymagane.
- Opcje płatności Opcje płatności.
- Sprawdzane są ograniczenia walutowe.
- W stosownych przypadkach sprawdzane są ograniczenia dotyczące kraju i operatora.
- Suma w koszyku została zweryfikowana.
- Odpowiedzi bramki zostały zweryfikowane.
- Podpisy wywołania zwrotnego są sprawdzane.
- Sprawdź zamówienie () zostanie wywołana dopiero po pomyślnej weryfikacji płatności.
- Kwota użyta do zamówienia jest weryfikowana na podstawie odpowiedzi bramki płatniczej.
- Webhooki są idempotentne.
- Zduplikowane powiadomienia nie powodują duplikowania zamówień.
- Zastosowano prawidłową kolejność stanów.
- Nieudane i oczekujące płatności są obsługiwane osobno.
- Dane dotyczące płatności nigdy nie są niepotrzebnie rejestrowane ani przechowywane.
- Wymuszony jest protokół HTTPS.
- Domyślna płatność PrestaShop została przetestowana.
- OPC zostało przetestowane osobno.
- JavaScript został przetestowany po odświeżeniu AJAX.
- Przetestowano ramki iframe i interaktywne elementy płatności.
- Przetestowano wiele modułów płatności jednocześnie.
- Przetestowano realistyczne koszyki z rabatami i wysyłką.
Wniosek
Spersonalizowana bramka płatności w PrestaShop to coś więcej niż integracja API.
API to tylko jeden z elementów implementacji. Prawdziwe wyzwanie inżynieryjne zaczyna się, gdy moduł płatności musi współistnieć z finalizacją zamówienia PrestaShop, OPC, takim jak SuperCheckout, innymi modułami płatności, dynamicznym JavaScriptem, przeliczaniem koszyka i asynchronicznymi wywołaniami zwrotnymi bramki.
Nasze doświadczenia z problemami ze zgodnością płatności utwierdziły nas w przekonaniu, że należy zawsze najpierw zlokalizować miejsce wystąpienia błędu, a dopiero potem wprowadzać zmiany w kodzie.
Jeśli metoda płatności nie jest zwracana przez PHP, sprawdź moduł płatności i jego zasady kwalifikowalności. Jeśli PHP zwraca metodę, ale klient jej nie widzi, sprawdź OPC i renderowanie front-endu. Jeśli interfejs użytkownika pojawia się, ale nie odpowiada, sprawdź JavaScript i odświeżanie AJAX. Jeśli płatność się powiedzie, ale zamówienie pozostaje oczekujące, sprawdź wywołanie zwrotne i przepływ stanu zamówienia.
To podejście jest o wiele bardziej niezawodne niż zakładanie, że każdy problem z płatnościami jest problemem API.
Deweloperzy pracujący nad integracją płatności PrestaShop nie powinni skupiać się wyłącznie na tym, aby bramka akceptowała transakcję. Chodzi o to, aby cały cykl płatności był niezawodny – od pierwszego wyświetlenie zamówienia do finalizacji zamówienia – nawet w przypadku korzystania z wielu metod płatności i niestandardowego OPC.
Jeśli masz pytania lub potrzebujesz pomocy w zakresie wydajności lub migracji witryny, nasi eksperci są do Twojej dyspozycji. Skontaktuj się z zespołem Knowband pod adresem [email chroniony] już dziś skorzystaj z niezawodnych wtyczek eCommerce dostosowanych do Twoich potrzeb.
