Integracja niestandardowej bramki płatności w PrestaShop: wymagania techniczne, przepływ API i wyzwania OPC w świecie rzeczywistym

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:

1. Wyświetl metodę płatności przy kasie.
2. Wyślij dane klienta lub płatności do bramki płatniczej.
3. Odbierz i zatwierdź odpowiedź bramy.
4. Utwórz lub zaktualizuj poprawnie zamówienie PrestaShop.
5. 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:

1. Wyrenderuj to.
2. Zachowaj je podczas odświeżania transakcji.
3. Zainicjuj wymagany JavaScript.
4. 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ć:

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.