Integration eines benutzerdefinierten Zahlungsgateways in PrestaShop: Technische Anforderungen, API-Ablauf und Herausforderungen im Bereich OPC in der Praxis

Die Integration eines Zahlungsgateways in PrestaShop mag auf dem Papier unkompliziert erscheinen.

Das Gateway stellt API-Dokumentation, Sandbox-Zugangsdaten, Authentifizierungsschlüssel, Callback-URLs und einige Endpunkte bereit. Das PrestaShop-Modul sendet anschließend die Zahlungsanfrage, empfängt die Antwort, erstellt die Bestellung und leitet den Kunden zur Bestätigungsseite weiter.

In einem realen PrestaShop-Shop arbeitet das Zahlungsgateway jedoch selten allein.

Sobald ein Shop ein One Page Checkout (OPC)-Modul wie SuperCheckout verwendet, können mehrere Zahlungsmodule, benutzerdefinierte Zahlungsabläufe, iFrames, JavaScript-basierte Zahlungsmethoden und zusätzliche Checkout-Anpassungen miteinander interagieren.

Hier stoßen viele Zahlungsintegrationen auf Schwierigkeiten.

Im Rahmen der Kompatibilitätsarbeiten mit Zahlungsgateways sind wir auf Fälle gestoßen, in denen eine Zahlungsmethode im Standard-Checkout von PrestaShop einwandfrei funktionierte, sich aber innerhalb von OPC anders verhielt. Beispielsweise konnte ein Zahlungsanbieter im Standard-Checkout korrekt angezeigt werden, während Optionen wie BLIK, Bankauswahl oder BNPL in SuperCheckout nicht mehr verfügbar waren.

Die wichtigste Erkenntnis war, dass die Integration eines Zahlungs-Gateways nicht nur bedeutet, den API-Aufruf zum Laufen zu bringen. Es geht darum, den gesamten Zahlungszyklus innerhalb des PrestaShop-Checkouts korrekt abzuwickeln.

1.0 Was benötigt ein kundenspezifisches Zahlungsgateway tatsächlich?

Im Wesentlichen muss eine PrestaShop-Zahlungsintegration fünf Dinge berücksichtigen:

1. Die Zahlungsmethode wird im Bestellvorgang angezeigt.
2. Senden Sie die Kunden- oder Zahlungsdaten an das Zahlungsportal.
3. Empfangen und validieren Sie die Gateway-Antwort.
4. Erstellen oder aktualisieren Sie die PrestaShop-Bestellung korrekt.
5. Leiten Sie den Kunden zur entsprechenden Bestätigungs- oder Fehlerseite zurück.

Ein typisches Zahlungsmodul erweitert die Basisklasse, anstatt sie zu erweitern.

Das Zahlungsmodul arbeitet normalerweise mit Hooks wie:

Der Hook sorgt dafür, dass die Zahlungsmethode im Checkout verfügbar ist.

Der Hook steuert, was der Kunde nach der Rückkehr vom Zahlungsvorgang sieht.

Beispielsweise:

public function hookPaymentOptions($params) { if (!$this->active || !$this->checkCurrency($params['cart'])) { return []; } $paymentOption = new PaymentOption(); $paymentOption ->setCallToActionText($this->l('Mit Karte bezahlen')) ->setAction( $this->context->link->getModuleLink( $this->name, 'redirect', [], true ) ); return [$paymentOption]; }

Wichtig ist, dass dieser Hook nicht einfach davon ausgehen sollte, dass die Zahlungsmethode immer angezeigt werden kann.

Währung, Land, Zahlungsdienstleister, Kundenstatus, Warenkorbwert, Modulkonfiguration und Verfügbarkeit des Zahlungsgateways können Einfluss darauf haben, ob die Zahlungsmethode angezeigt werden soll.

2.0 Der Teil, der alles verändert: OPC

Der standardmäßige PrestaShop-Checkout und ein OPC-Modul verarbeiten Zahlungsmethoden nicht unbedingt auf genau die gleiche Weise.

Dies war eine der wichtigsten Erkenntnisse aus der Arbeit mit verschiedenen Zahlungsmodulen.

Bei der Standard-Kasse steuert ein Zahlungsmodul im Allgemeinen die Darstellung seiner eigenen Zahlungsoptionen und den Zahlungsablauf.

Mit einem OPC wird das Checkout-Modul zu einer weiteren Schicht zwischen dem Zahlungsmodul und dem Kunden. Das bedeutet, dass folgende Komponenten interagieren können:

Durch den
↓
OPC / SuperCheckout
↓
Zahlungsmöglichkeiten
↓
Zahlungsmodul
↓
Gateway-API
↓
Gateway-Antwort
↓
Zahlungsmodul
↓
OPC / PrestaShop
↓
Auftragsbestätigung

Ein Zahlungsmodul kann daher aus API-Sicht völlig korrekt sein und dennoch innerhalb eines OPC nicht korrekt funktionieren.

Deshalb sollte die Prüfung der Zahlungskompatibilität immer beides umfassen:

• PrestaShop Standard-Checkout
• Der tatsächliche OPC, der vom Geschäft verwendet wird

Wenn man nur den Standard-Checkout testet, kann das fälschlicherweise den Eindruck erwecken, die Integration sei abgeschlossen.

3.0 Ein Beispiel aus der Praxis: Fehlende PayU-Optionen in OPC

Eines der praktischen Probleme, auf die wir stießen, betraf die Zahlungsoptionen von PayU.

Im Standard-Checkout von PrestaShop wurden die verfügbaren Zahlungsmethoden von PayU korrekt angezeigt. Im SuperCheckout fehlten jedoch einige Zahlungsoptionen.

Zum Beispiel abhängig von der Konfiguration und dem Warenkorb:

• BLIK war nicht durchgehend sichtbar.
• Die Bankauswahlliste wurde nicht korrekt erweitert.
• Einige BNPL-/Zahlungszeilen fehlten.
• In einigen Fällen erschien BLIK und verschwand dann wieder.

Auf den ersten Blick sah das nach einem Problem mit der PayU-API aus. War es aber nicht.

Der wichtigste Diagnoseschritt war der Vergleich des Zahlungsablaufs zwischen dem Standard-Checkout und SuperCheckout.

Wenn dasselbe Zahlungsmodul im Standard-Checkout funktioniert, aber innerhalb von OPC fehlschlägt, sollte die Untersuchung über die Gateway-API hinausgehen.

Wir müssen überprüfen, wie der OPC die Zahlungsmethoden erstellt und welche Informationen er an die Zahlungsmodule weitergibt.

4.0 Die Höhe des Zahlungsbetrags kann die Sichtbarkeit der Zahlungsmethode beeinflussen

Ein besonders wichtiger Aspekt dieser Untersuchung war der Warenkorbwert. Zahlungsanbieter haben häufig Mindest- und Höchstbeträge für Transaktionen. Zum Beispiel:

Bezahlverfahren
↓
Warenkorbbetrag prüfen
↓
Mindestbetrag? Höchstbetrag?
↓
Berechtigt / Nicht berechtigt

Im Rahmen der PayU-Kompatibilitätsuntersuchung konnten wir feststellen, dass die Logik zur Filterung der Zahlungsmethoden darin besteht, dass der Warenkorbbetrag die Prüfungen der Zahlungsmethoden durchläuft.

Der relevante Ablauf umfasste die Warenkorbberechnung und die Filterung der Zahlungsmethoden von PrestaShop, einschließlich der Logik rund um Folgendes:

Warenkorb::BEIDE

und:

PayMethodsCache::checkMinMax

Dies ist deshalb wichtig, weil eine Zahlungsoption im Bezahlvorgang verschwinden kann, ohne dass die API selbst einen Fehler zurückgibt.

Das Zahlungsgateway kann schlichtweg als nicht berechtigt für den vom Zahlungsmodul empfangenen Betrag angesehen werden. Daraus ergibt sich eine wichtige Regel für die Fehlersuche:

Wenn eine Zahlungsoption in einem OPC nicht mehr angezeigt wird, gehen Sie nicht sofort davon aus, dass die Zahlungs-API defekt ist. Überprüfen Sie zunächst den Warenkorbwert, die Währung, die Mindest- und Höchstbeträge sowie die Werte, die die Prüfungen zur Zahlungsberechtigung erfüllen.

Dies gewinnt noch mehr an Bedeutung, wenn Rabatte, Versandkosten, Steuern, Gutscheine oder individuelle Berechnungen im Bestellprozess ins Spiel kommen.

5.0 Warum Zahlungsmethoden im Standard-Checkout funktionieren, aber im SuperCheckout fehlschlagen

Eine hilfreiche Methode zur Untersuchung dieser Probleme ist der Vergleich der beiden Checkout-Umgebungen.

5.1 Standard-PrestaShop-Checkout

Warenkorb
↓
Zahlungsoptionenfinder
↓
Zahlungsoptionen-Hooks
↓
Zahlungsmodule
↓
Zahlungsmöglichkeiten

5.2 OPC-Checkout

Warenkorb
↓
SuperCheckout
↓
Zahlungsmethoden
↓
Zahlungsmodule
↓
Zusätzliche OPC-Verarbeitung
↓
Gerenderte Zahlungs-UI

Der zweite Durchfluss weist zusätzliche bewegliche Teile auf.

Deshalb prüfen wir bei der Fehlersuche in Zahlungsproblemen nicht nur: „Funktioniert das Zahlungsmodul?“

Wir überprüfen: Funktioniert das Zahlungsmodul, wenn seine Ausgabe von dieser speziellen Checkout-Implementierung verarbeitet und dargestellt wird?

Diese Unterscheidung sparte eine beträchtliche Menge an Fehlersuchezeit.

6.0 Die Zahlungsoption ist nur ein Teil der Integration.

Ab PrestaShop 1.7 verwenden Zahlungsmodule im Allgemeinen die ältere Methode des Payment Hooks, um Zahlungs-HTML auszugeben.

Eine Zahlungsoption kann beispielsweise folgende Informationen enthalten:

Zahlungsoption
->setCallToActionText(...)
->setAction(...)
->setInputs(...)
->setAdditionalInformation(...)

Objekte statt direkt

Unterschiedliche Gateways erfordern unterschiedliche Kombinationen.

6.1 Umleitungsbasiertes Gateway

Der Kunde klickt auf die Zahlungsmethode und wird zum Zahlungsportal weitergeleitet.

Zur Kasse
↓
Zahlungsoption
↓
Modulsteuerung
↓
Gateway

6.2 Eingebettetes Zahlungsformular

Die Zahlungsfelder werden direkt im Checkout angezeigt.

Zur Kasse
↓
Zahlungsoption
↓
Karten-/Zahlungsformular
↓
Gateway-API

6.3 Iframe-basierte Zahlung

Die Schnittstelle des Zahlungsportals ist in den Bezahlvorgang integriert.

Zur Kasse
↓
Zahlungsoption
↓
Iframe
↓
Gateway

Die letzten beiden Ansätze erfordern besondere Aufmerksamkeit, da JavaScript, DOM-Manipulation, das Laden von iFrames und OPC-Aktualisierungen die Zahlungsschnittstelle beeinträchtigen können.

7.0 JavaScript wird mit OPC unerlässlich.

Dies ist ein Bereich, der in allgemeinen Leitfäden zur Zahlungsintegration oft vernachlässigt wird.

Ein OPC kann Teile des Checkouts dynamisch aktualisieren, wenn sich die Kundendaten ändern:

• Lieferadresse
• Land
• Träger
• Zahlungsmethode
• Abrechnungsdaten
• Versandart

Wenn das passiert, kann der zahlungsbezogene HTML-Code ersetzt werden.

Ein JavaScript-Ereignis, das beim ersten Laden der Seite noch funktionierte, kann daher nach einer AJAX-Aktualisierung möglicherweise nicht mehr funktionieren.

Beispielsweise:

Erster Checkout-Ladevorgang
↓
Payment JS initialisiert
↓
Kunde ändert Zahlungs-/Versandinformationen
↓
OPC aktualisiert den Zahlungsbereich
↓
Original DOM ersetzt
↓
Payment JS ist nicht mehr angehängt

Dies kann zu verwirrenden Symptomen führen.

Die Zahlungsmethode wird möglicherweise zunächst angezeigt, aber ein Klick darauf hat keine Auswirkung. Ein iFrame kann verschwinden.

Eine Bankenliste könnte nicht weiter erweitert werden.

Eine Zahlungsoption kann erscheinen und wieder verschwinden, nachdem sich ein anderes Feld im Bestellprozess geändert hat.

Daher erfordern Kompatibilitätsarbeiten oft Änderungen nicht nur im PHP-Code, sondern auch im JavaScript des Zahlungsmoduls.

8.0 Ein praktisches Beispiel: SimplyLease + SuperCheckout

Ein weiteres Beispiel betraf die Integration von SimplyLease mit SuperCheckout. Das Problem beschränkte sich nicht auf die Gateway-API.

Einige Informationen und Rechnerelemente von SimplyLease waren Teil der Checkout-/Zahlungsdarstellung und mussten innerhalb des SuperCheckout-Ablaufs korrekt funktionieren.

Die Kompatibilitätsänderungen betrafen sowohl Modulvorlagen als auch die JavaScript-Integration auf SuperCheckout-Seite. Zu den betroffenen Dateien gehörten:

modules/simplylease/views/templates/hook/payment_info.tpl modules/simplylease/views/templates/hook/product_calculator.tpl

modules/supercheckout/controllers/front/SupercheckoutCore.php modules/supercheckout/views/js/front/supercheckout.js
modules/supercheckout/views/js/front/simplylease_supercheckout.js

Dies ist ein gutes Beispiel dafür, warum die Zahlungskompatibilität manchmal Änderungen außerhalb des Zahlungsgateway-Moduls selbst erfordert.

Der Zahlungsanbieter mag die korrekten Daten anzeigen, aber der Bezahlvorgang muss dennoch Folgendes leisten:

1. Rendere es.
2. Behalten Sie es bei Aktualisierungen des Bestellvorgangs bei.
3. Initialisieren Sie das benötigte JavaScript.
4. Halten Sie die Zahlungsinformationen mit dem aktuellen Warenkorb synchronisiert.

9.0 Ein weiteres häufiges Problem: Zahlungsmethode wird nicht angezeigt

Wir stießen auch auf Fälle, in denen eine Zahlungsmethode wie Comfino in SuperCheckout nicht angezeigt wurde, obwohl das Zahlungsmodul selbst installiert und konfiguriert war.

Diese Art von Problem sollte systematisch untersucht werden.

Prüfen:

9.1 Ist das Modul aktiv?

$this->active

9.2 Wird die Währung unterstützt?

$this->checkCurrency($params['cart'])

9.3 Wird das Land unterstützt?

Manche Zahlungsanbieter schränken die Zahlungsmethoden je nach Land des Kunden ein.

9.4 Liegt der Gesamtbetrag im Warenkorb innerhalb der vom Zahlungsanbieter festgelegten Grenzen?

Minimale und maximale Transaktionswerte können verhindern, dass eine Methode angezeigt wird.

9.5 Wird der Mobilfunkanbieter unterstützt?

Manche Zahlungsmodule beschränken die Zahlungsmethoden nach Anbieter.

9.6 Ist OPC-Filterung die Methode?

Das Zahlungsmodul kann gültige Zahlungsmethoden zurückgeben, die gesammelt, gefiltert oder gerendert werden. Die OPC kann aber weiterhin die Zahlungsweise ändern.

9.7 Wird das Element durch JavaScript ausgeblendet oder ersetzt?

Eine Zahlungsmethode kann technisch gesehen von PHP zurückgegeben werden, ist aber im endgültigen Bezahlvorgang trotzdem nicht sichtbar.

Aus diesem Grund sind Browser-Entwicklertools bei der Fehlersuche in Zahlungsintegrationen genauso wichtig wie PHP-Protokolle.

10.0 Haken, auf die wir tatsächlich achten müssen

Eine kundenspezifische Zahlungsintegration sollte nicht als Einzel-Hook-Implementierung behandelt werden.

Die genauen Schnittstellen hängen von der Architektur des Zahlungsportals und des Bezahlvorgangs ab, einige sind jedoch besonders wichtig.

10.1 Zahlungsoptionen

Dies ist der primäre Ansatzpunkt, um die Zahlungsmethode im Checkout-Prozess anzuzeigen.

Es ist für die Rückgabe verantwortlich Zahlungsoptionen Objekte.

Typische Prüfungen umfassen:

if (!$this->active) { return [];
}
if (!$this->checkCurrency($params['cart'])) { return [];
}

Anschließend können zusätzliche gatewayspezifische Beschränkungen angewendet werden.

10.2 Zahlungsrückgaben

Dies wird verwendet, nachdem der Kunde den Zahlungsvorgang abgeschlossen oder abgebrochen hat. Es kann Folgendes anzeigen:

• Bestellnummer
• Zahlungsstatus
• zusätzliche Zahlungsanweisungen
• Gatewayspezifische Informationen

10.3 actionPresentPaymentOptions

Dieser Hook wird besonders interessant, wenn mehrere Zahlungsmodule und ein OPC involviert sind.

Es arbeitet mit den zusammengestellten Zahlungsoptionen und kann nützlich sein, wenn der Checkout die gesamte Sammlung an Zahlungsoptionen überprüfen oder ändern muss.

Dies unterscheidet sich von der Implementierung der Zahlungsoptionen eines einzelnen Zahlungsgateways. Haken.

Die Unterscheidung ist wichtig:

Zahlungsoptionen
↓
Jedes Zahlungsmodul trägt seine Option bei
actionPresentPaymentOptions
↓
Die zusammengestellten Zahlungsoptionen können verarbeitet werden

Bei der Fehlersuche in Bezug auf die OPC-Kompatibilität kann das Verständnis dafür, wo Zahlungsoptionen erfasst und wo sie letztendlich angezeigt werden, den entscheidenden Unterschied ausmachen, ob man das Problem schnell findet oder stundenlang im Gateway-Modul verbringen muss.

11.0 Auftragserstellung: Vertrauen Sie niemals dem Browser

Sobald die Zahlung beim Zahlungsportal eingegangen ist, ist der nächste entscheidende Schritt die Erstellung der Bestellung. Die wichtigste PrestaShop-Methode hierfür ist:

validateOrder()

Ein vereinfachtes Beispiel ist:

$this->module->validateOrder(
$cart->id, Configuration::get('PS_OS_PAYMENT'),
Bezahlter Betrag
$paymentMethod,
$message, [],
null, falsch,
$customer->secure_key
);

Drei Werte verdienen besondere Beachtung:

11.1 Warenkorb-ID

Der Warenkorb muss zum erwarteten Kunden/zur erwarteten Sitzung gehören und gültig sein.

11.2 Zahlungsbetrag

Nicht blind verwenden:

$cart->getOrderTotal()

als Beweis dafür, dass das Gateway diesen Betrag erhalten hat.

Der Betrag sollte anhand der Antwort des Gateways überprüft werden.

11.3 Sicherer Schlüssel

Die Kunden muss korrekt dem Warenkorb-/Bestellprozess zugeordnet sein.

12.0 Webhooks müssen idempotent sein

Ein Zahlungsportal kann denselben Webhook mehrmals senden. Zum Beispiel:

Gateway
↓
Webhook
↓
Ihr Server
↓
200 Antwort

Wenn die Antwort ausbleibt:

Gateway
↓
Webhook
↓
Ihr Server
↓
Antwort verloren
↓
Gateway-Wiederholungsversuche

Wenn die Integration bei jedem Webhook-Empfang eine Bestellung erstellt, können doppelte Bestellungen entstehen. Daher sollte der Callback prüfen, ob sich bereits eine Bestellung im Warenkorb befindet, bevor eine weitere erstellt wird. Konzeptionell:

if ($cart->OrderExists()) {
// Bereits verarbeitet
// Erfolgreiche Antwort zurückgeben
}

Der Webhook-Handler sollte so konzipiert sein, dass er wiederholte Benachrichtigungen sicher verarbeiten kann.

13.0 Synchrone vs. asynchrone Zahlung

Nicht alle Zahlungsanbieter bestätigen die Zahlung sofort.

13.1 Synchron

Das Zahlungsportal bestätigt die Transaktion umgehend.

Durch den
↓
Gateway
↓
Zahlung genehmigt
↓
validateOrder()
↓
PS_OS_ZAHLUNG
↓
Bestätigung

13.2 Asynchron

Der Kunde kann vor Erhalt der endgültigen Zahlungsbestätigung zurückkehren.

Durch den
↓
Gateway
↓
Gehen Sie zum Speicher zurück
↓
Ausstehende Bestellung
↓
Webhook
↓
Zahlung prüfen
↓
Status der Auftragsänderung
↓
Zahlung akzeptiert

Bei asynchronen Zahlungsgateways ist die Verwendung eines dedizierten Status „Auftrag ausstehend“ oft sicherer als die sofortige Kennzeichnung des Auftrags als bezahlt.

Sobald der Webhook die Zahlung bestätigt hat:

$history = new OrderHistory();
$history->id_order = (int) $order->id;
$history->changeIdOrderState( Configuration::get('PS_OS_PAYMENT'),
$Bestellung
);
$history->addWithemail(true);

Dadurch wird sichergestellt, dass der Bestellstatusübergang über den Bestellhistorienmechanismus von PrestaShop erfolgt und nicht einfach der Datenbankwert geändert wird.

14.0 Eine der nützlichsten Debugging-Techniken: Vergleich der Checkout-Abläufe

Wenn eine Zahlungsmethode im Standard-Checkout funktioniert, aber nicht im OPC-Checkout, empfehlen wir, den gesamten Ablauf zu vergleichen.

Schritt 1: PHP überprüfen

Ist hookPaymentOptions() ausgeführt?

Schritt 2: Überprüfen Sie die zurückgegebenen Optionen

Gibt das Zahlungsmodul tatsächlich einen Wert zurück? Zahlungsoption?

Schritt 3: Warenkorb überprüfen

Vergleichen Sie:

• gesamt
• Währung
• Kunde
• Land
• Träger
• exklusive Rabatte
• Steuern
• Versand

Schritt 4: Überprüfen Sie den Browser

Suchen:

• JavaScript-Fehler
• fehlende DOM-Elemente
• AJAX-Anfragen
• fehlgeschlagene Anfragen
• iFrame-Fehler

Schritt 5: Überprüfen Sie den OPC

Ermitteln Sie, ob SuperCheckout Folgendes ist:

• Filtern der Zahlungsoption
• ersetzt dessen HTML
• Aktualisierung des Zahlungsbereichs
• Die Änderung des Warenkorbs erfolgt, bevor das Zahlungsmodul ausgeführt wird.

Schritt 6: Gateway überprüfen

Erst wenn der lokale Checkout-Prozess bestätigt ist, sollte die Untersuchung in folgende Bereiche vertieft werden:

• API-Authentifizierung
• Anfragenutzdaten
• Stempel, Unterschrift
• Antwort
• Webhook
• Gateway-Protokolle

Dieser mehrschichtige Ansatz ist wesentlich schneller, als jedes Mal mit der Gateway-API zu beginnen.

15.0 Häufige Probleme bei der Zahlungsintegration, die wir beobachtet haben

Kompatibilitätsprüfungen in der Praxis decken in der Regel Probleme auf, die aus der Gateway-Dokumentation nicht ersichtlich sind.

15.1 Die Zahlungsoption verschwindet

Mögliche Ursachen:

• nicht unterstützte Währung
• Länderbeschränkung
• Warenkorbmenge außerhalb der Gateway-Limits
• Beschränkung des Anbieters
• OPC-Filterung
• Konfiguration des Zahlungsmoduls
• JavaScript, das die Methode ausblendet

15.2 BLIK oder eine andere Zahlungsoption erscheint und verschwindet

Mögliche Ursachen:

• Checkout-AJAX-Aktualisierung
• Zahlungsoption erneut rendern
• JavaScript-Initialisierung
• Warenkorbwert ändert sich
• Die Zulassungsvoraussetzungen werden neu berechnet

15.3 Die Bankenliste wird nicht erweitert

Häufig untersuchen:

• JavaScript-Fehler
• dynamisch ersetzte DOM-Elemente
• Ereignisbehandler wurden vor der OPC-Aktualisierung angehängt.
• JavaScript-Initialisierung des Zahlungsanbieters

15.4 Iframe verschwindet

Untersuchen:

• Aktualisierung des Kassenvorgangs
• iFrame-Initialisierung
• DOM-Ersatz
• JavaScript-Ausführung nach AJAX-Aktualisierungen
  

15.5 Zahlung erfolgreich, Bestellung bleibt aber ausstehend

Prüfen:

• Webhook-URL
• Webhook-Zustellung
• Signaturprüfung
• Warenkorb-/Bestellabfrage
• Ordnungszustandsübergang
• Callback-Authentifizierung

15.6 Die Zahlungsmethode funktioniert im Standard-Checkout, aber nicht im OPC-Checkout.

Dies ist ein starkes Indiz dafür, dass das Problem eher in der Interaktion zwischen dem Zahlungsmodul und dem OPC als in der Gateway-API selbst liegt.

16.0 Sicherheitsanforderungen an ein Zahlungsmodul

Da Zahlungsmodule sensible Vorgänge verarbeiten, darf Sicherheit nicht als optionale Verbesserung betrachtet werden. Mindestens erforderlich:

• Callback-Signaturen validieren.
• Überprüfen Sie die Beziehung zwischen Warenkorb und Kunde.
• Verwenden Sie HTTPS.
• TLS-Zertifikate validieren.
• Vertrauen Sie niemals ausschließlich dem Zahlungsstatus, der vom Browser angezeigt wird.
• Speichern Sie niemals Rohdaten von Kartendaten, es sei denn, die Architektur und die Compliance-Anforderungen lassen dies ausdrücklich zu.
• Sensible Zahlungsinformationen dürfen nicht protokolliert werden.
  

• Vermeiden Sie serialize() und unserialize(). / für nicht vertrauenswürdige externe Daten.

• Eingehende Werte prüfen und umwandeln.
• Schützen Sie benutzerdefinierte AJAX- und Callback-Endpunkte.
• Verwenden Sie gegebenenfalls sichere Token.
• Die Webhook-Verarbeitung soll idempotent sein.

Eine Zahlungsbestätigungsseite ist kein Zahlungsnachweis.

Die vom Gateway verifizierte serverseitige Antwort sollte darüber entscheiden, ob die Bestellung als bezahlt gilt.

17.0 Was ändert sich bei der Unterstützung mehrerer Zahlungsmodule?

Eine weitere Erkenntnis aus der Arbeit zur OPC-Kompatibilität ist, dass das Hinzufügen eines zweiten oder dritten Zahlungsmoduls Probleme aufdecken kann, die nicht sichtbar waren, als nur eine Zahlungsmethode existierte.

Beispielsweise:

PayPal PayU
Comfino
SimplyLease
Banküberweisung

Alle diese Zahlungsoptionen können zum selben Checkout beitragen. Der Checkout muss daher mit verschiedenen Zahlungsarten umgehen:

• HTML-Strukturen
• JavaScript
• Anforderungen an iFrames
• Umleitungen
• API-Abläufe
• Zulassungsregeln
• Mindest-/Höchstbeträge
• asynchrone Rückrufe

Eine Änderung an einer Zahlungsmethode kann versehentlich Auswirkungen auf andere haben. Deshalb sollten Korrekturen zur Verbesserung der Zahlungskompatibilität eng gefasst sein.

Anstatt beispielsweise die gesamte Logik der Zahlungsoptionenverarbeitung global zu ändern, sollte man die jeweilige Zahlungsmethode identifizieren und die Kompatibilitätsbehandlung nur dort anwenden, wo sie erforderlich ist.

18.0 Die Tests sollten reale Warenkorb-Szenarien umfassen.

Es genügt nicht, ein Zahlungsportal mit einem einfachen Produkt im Wert von 10 € zu testen. Eine ordnungsgemäße Testmatrix sollte Folgendes beinhalten:

Testen Sie bei OPC-Integrationen auch die Aktualisierung des Checkouts. Ändern Sie Folgendes:

• Adresse
• Träger
• Land
• Zahlungsmethode
• Menge
• Rabatt

und überprüfen Sie, ob die Zahlungsoptionen nach jeder Aktualisierung noch korrekt sind.

19.0 Ein praktischer Entwicklungsansatz

Ausgehend von den Problemen, die häufig bei realen Integrationen auftreten, ist folgende Entwicklungsreihenfolge sicherer:

19.1 Das Gateway mit dem Standard-PrestaShop-Checkout kompatibel machen

Zunächst muss Folgendes festgestellt werden:

Zahlungsoption
↓
Gateway-Anfrage
↓
Gateway-Antwort
↓
validateOrder()
↓
Bestätigung

funktioniert richtig.

19.2 Hinzufügen von Callback-/Webhook-Verarbeitung

Die asynchrone Bestätigung sollte nicht bis zum Schluss aufgeschoben werden.

19.3 Korrekte Auftragsstatusbehandlung hinzufügen

Test:

• Erfolg
• Fehler
• schwebend
• Timeout

19.4 Test mit realistischen Wagen

Nutzen Sie Rabatte, Versandkosten, Steuern, verschiedene Währungen und unterschiedliche Gesamtbeträge.

19.5 Integration mit OPC

Erst wenn der grundlegende Gateway-Ablauf stabil ist, sollten Sie die SuperCheckout-Kompatibilität untersuchen.

19.6 JavaScript und dynamische Aktualisierungen testen

Dies ist besonders wichtig für eingebettete Zahlungsformulare, iFrames, BLIK-/Bankauswahlschnittstellen und andere interaktive Zahlungskomponenten.

19.7 Testen Sie alle Zahlungsmethoden gleichzeitig

Ein Checkout-System, das fünf Zahlungsmethoden unterstützt, muss als Gesamtsystem getestet werden, nicht als fünf isolierte Module.

20.0 Sollten Sie ein benutzerdefiniertes Gateway entwickeln oder ein vorhandenes Modul verwenden?

Nicht jedes Gateway rechtfertigt eine individuelle Integration. Ein individuelles Modul ist sinnvoll, wenn:

• Das Gateway ist regional oder Nischenprodukt.
• Es gibt kein gepflegtes PrestaShop-Modul.
• Das Gateway erfordert benutzerdefinierte Geschäftslogik
• Sie benötigen einen bestimmten Abonnement- oder Abrechnungsablauf.
• Sie benötigen Funktionen, die bestehende Module nicht bereitstellen können.

Die Entwicklung einer Zahlungsintegration bedeutet aber auch die Übernahme der Wartungsverantwortung. PrestaShop ändert sich.

PHP ändert sich. Gateway-APIs ändern sich.

Die Sicherheitsanforderungen ändern sich. Die Checkout-Module ändern sich.

Und schließlich ändert der Zahlungsanbieter etwas, was eine ansonsten stabile Integration beeinträchtigt.

Für gängige Zahlungsgateways kann ein etabliertes und gepflegtes Modul daher deutlich günstiger sein als die jahrelange Pflege eines individuellen Zahlungscodes.

21.0 Die wichtigste Erkenntnis aus der PrestaShop-Zahlungsintegration

Die wichtigste Erkenntnis aus der Arbeit mit Zahlungsportalen ist, dass die API oft nicht der schwierigste Teil ist. Senden:

API-Anfrage → API-Antwort

ist in der Regel unkompliziert.

Das Schwierige ist alles drumherum:

┌── Währungsregeln
├── Landesregeln
├── Warenkorbmenge
├── Beschränkungen des Mobilfunkanbieters
├── OPC
├── JavaScript
├── Iframes
├── AJAX-Aktualisierungen
├── Webhooks
├── Die Anordnung besagt:
└── Doppelte Benachrichtigungen
↓
Durch den → Zur Kasse → Zahlungsmodul → Gateway
↓
Auftragserstellung
↓
Auftragsbestätigung

Eine Zahlungsintegration ist nur dann erfolgreich, wenn sich die gesamte Kette einheitlich verhält.

Aus diesem Grund sollte ein Problem wie „BLIK fehlt“ oder „Die Bankenliste lässt sich nicht öffnen“ nicht sofort als Gateway-API-Problem behandelt werden.

Die eigentliche Ursache könnte eine Berechnung des Warenkorbwerts, eine Überprüfung der Berechtigung für die Zahlungsmethode, eine OPC-Darstellung, eine JavaScript-Initialisierung oder eine AJAX-Aktualisierung sein, die die Zahlungsschnittstelle ersetzt.

22.0 Abschließende Checkliste für ein benutzerdefiniertes PrestaShop-Zahlungsgateway

Bevor Sie die Integration als abgeschlossen betrachten, überprüfen Sie Folgendes:

• Das Zahlungsmodul erweitert Zahlungsmodul.
• Zahlungsoptionen ist korrekt implementiert.
• Zahlungsrückgabe wird bei Bedarf umgesetzt.
• Zahlungsoptionen Zahlungsoptionen.
• Währungsbeschränkungen werden geprüft.
• Länderspezifische und Fluggesellschaftsbeschränkungen werden gegebenenfalls geprüft.
• Die Warenkorbsummen wurden überprüft.
• Die Gateway-Antworten werden überprüft.
• Callback-Signaturen werden validiert.
  
• Bestellung validieren() wird erst nach erfolgreicher Zahlungsbestätigung aufgerufen.
• Der für die Bestellung verwendete Betrag wird anhand der Antwort des Zahlungsportals validiert.
• Webhooks sind idempotent.
• Doppelte Benachrichtigungen führen nicht zu doppelten Bestellungen.
• Die korrekte Reihenfolge der Zustände wird verwendet.
• Fehlgeschlagene und ausstehende Zahlungen werden separat behandelt.
• Sensible Zahlungsdaten werden niemals unnötig protokolliert oder gespeichert.
• HTTPS wird erzwungen.
• Der Standard-Checkout von PrestaShop wurde getestet.
• OPC wurde separat getestet.
• JavaScript wurde nach Aktualisierungen des AJAX-Checkouts getestet.
• Es wurden Iframes und interaktive Zahlungselemente getestet.
• Es wurden mehrere Zahlungsmodule gemeinsam getestet.
• Realistische Warenkörbe mit Rabatten und Versandkosten wurden getestet.

Fazit

Ein individuelles Zahlungsgateway in PrestaShop ist mehr als nur eine API-Integration.

Die API ist nur ein Teil der Implementierung. Die eigentliche technische Herausforderung beginnt, wenn das Zahlungsmodul mit dem PrestaShop-Checkout, einem OPC wie SuperCheckout, anderen Zahlungsmodulen, dynamischem JavaScript, Warenkorb-Neuberechnungen und asynchronen Gateway-Callbacks koexistieren muss.

Unsere Erfahrungen mit Kompatibilitätsproblemen bei Zahlungen haben uns einen wichtigen Ansatz verdeutlicht: Man muss immer zuerst herausfinden, wo der Fehler auftritt, bevor man den Code ändert.

Wird die Zahlungsmethode von PHP nicht zurückgegeben, überprüfen Sie das Zahlungsmodul und dessen Berechtigungsregeln. Gibt PHP die Zahlungsmethode zurück, der Kunde sieht sie aber nicht, überprüfen Sie OPC und Frontend-Rendering. Wird die Benutzeroberfläche angezeigt, reagiert aber nicht, überprüfen Sie JavaScript- und AJAX-Aktualisierungen. Ist die Zahlung erfolgreich, die Bestellung aber noch ausstehend, überprüfen Sie den Callback und den Bestellstatusablauf.

Dieser Ansatz ist wesentlich zuverlässiger als die Annahme, dass jedes Zahlungsproblem ein API-Problem ist.

Für Entwickler, die an PrestaShop-Zahlungsintegrationen arbeiten, sollte das Ziel nicht einfach darin bestehen, dass ein Zahlungsgateway eine Transaktion akzeptiert. Vielmehr geht es darum, den gesamten Zahlungszyklus zuverlässig zu gestalten – vom ersten Rendern des Checkouts bis zum endgültigen, bestätigten Bestellstatus –, selbst bei der Verwendung mehrerer Zahlungsmethoden und eines benutzerdefinierten OPC-Codes.