VibeFox Peach Payments for PrestaShop — Hilfe
Anforderungen
PrestaShop: 8.0 bis 9.x.
PHP: 8.0 oder neuer mit der OpenSSL-Erweiterung (wird zum Entschlüsseln der Webhooks benötigt). Ohne sie lässt sich das Modul nicht installieren.
Währung: Die Warenkorbwährung muss ZAR, KES oder MUR sein. Bei Warenkörben in anderen Währungen wird die Zahlungsart ausgeblendet. Die Einstellungsseite warnt Sie, wenn die Standardwährung des Shops keine davon ist.
Peach Payments-Konto: Sie benötigen die Card API-Zugangsdaten Ihres Peach Payments-Kontos: die Entity ID und den Access Token. Testzugangsdaten stammen aus dem Sandbox-Dashboard von Peach Payments, Live-Zugangsdaten aus dem Dashboard von Peach Payments; sie sind unterschiedlich. Für Webhooks benötigen Sie außerdem einen Webhook-Entschlüsselungsschlüssel, den Peach Payments Ihnen zusendet, wenn Card-Webhooks für Ihren Shop aktiviert werden (siehe Konfiguration). Ihr Shop muss aus dem Internet erreichbar sein, um Webhooks zu empfangen.
VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer Domain.
Installation
1. Gehen Sie im Back-Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls.
2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Peach Payments Pay Gateway in der Modulliste und klicken Sie auf Configure.
3. Geben Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).
4. Geben Sie die Test-Entity-ID und den Test-Access-Token aus dem Sandbox-Dashboard von Peach Payments ein und bitten Sie Peach Payments, Card-Webhooks für die auf der Einstellungsseite angezeigte Webhook-URL zu aktivieren (siehe Konfiguration).
5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Lassen Sie Test mode eingeschaltet und führen Sie eine Zahlung mit einer Testkarte der Peach Payments-Sandbox durch. Schalten Sie danach Test mode aus, geben Sie die Live-Zugangsdaten und den Live-Webhook-Schlüssel ein und klicken Sie auf Save.
Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Peach Payments payment und Peach Payments payment on hold. PrestaShop bietet ein neues Zahlungsmodul für die Währungen, Länder und Kundengruppen an, die zu diesem Zeitpunkt aktiv sind. Später hinzugefügte Länder müssen unter Payment > Preferences für das Modul aktiviert werden; dort können Sie sie auch einschränken.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite Hinweise an: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.; einen Fehler, wenn Entity ID oder Access Token des aktuellen Modus fehlen (bis dahin wird die Zahlungsart im Checkout nicht angezeigt); eine Warnung, wenn der Webhook-Entschlüsselungsschlüssel des aktuellen Modus fehlt (dann werden Zahlungen nur bestätigt, wenn der Kunde in den Shop zurückkehrt); und einen Fehler, wenn die Standardwährung des Shops nicht unterstützt wird. Beim Speichern werden Leerzeichen aus den Zugangsdaten entfernt, und ein Webhook-Schlüssel, der kein 64-stelliger hexadezimaler Wert ist, wird mit einer Warnung gemeldet.
Peach Payments
Enable/Disable: Enable Peach Payments schaltet die Zahlungsart ein oder aus. Standard: aus.
Title: der Name der Zahlungsart, den der Kunde im Checkout sieht. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Credit / Debit Card (Peach Payments). Pflichtfeld.
Description: der Text, der im Checkout unter der Zahlungsart angezeigt wird. Standard: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.
API credentials
Der Access Token und die Entity ID der Card API werden im Dashboard von Peach Payments angezeigt (Testzugangsdaten: im Sandbox-Dashboard). Der Abschnitt verlinkt beide Dashboards und die Entwicklerdokumentation von Peach Payments.
Test mode: sendet neue Zahlungen mit den Testzugangsdaten an die Sandbox von Peach Payments; es wird kein echtes Geld abgebucht. Schalten Sie den Modus aus, um echte Zahlungen mit den Live-Zugangsdaten anzunehmen. Eine im einen Modus gestartete Zahlung wird immer in diesem Modus geprüft, auch nachdem Sie umgeschaltet haben. Standard: ein.
Test Entity ID: die Entity ID (3-D-Secure-Kanal) Ihres Sandbox-Kontos.
Test Access Token: das Bearer-Zugriffstoken Ihres Sandbox-Kontos.
Test Webhook Decryption Key: der 64-stellige hexadezimale Schlüssel, mit dem die Card-Webhooks der Sandbox entschlüsselt werden.
Live Entity ID: die Entity ID (3-D-Secure-Kanal) Ihres Live-Kontos.
Live Access Token: das Bearer-Zugriffstoken Ihres Live-Kontos.
Live Webhook Decryption Key: der 64-stellige hexadezimale Schlüssel, mit dem die Card-Webhooks Ihres Live-Kontos entschlüsselt werden.
Gespeicherte Access Tokens und Webhook-Schlüssel werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.
Clear saved secrets: Setzen Sie ein Häkchen bei einem Access Token oder Webhook-Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Webhook
Webhooks bestätigen Zahlungen auch dann, wenn der Kunde den Browser schließt, bevor er in den Shop zurückkehrt. Das Feld Webhook URL zeigt die Webhook-URL Ihres Shops. Mit SEO-freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_peach_pay/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen. Bitten Sie Peach Payments (support@peachpayments.com), Card-Webhooks für Ihr Konto mit dieser URL zu aktivieren, und tragen Sie dann den erhaltenen Entschlüsselungsschlüssel im Feld Webhook Decryption Key desselben Modus ein.
Peach Payments verschlüsselt jeden Webhook (AES-256-GCM). Ein Webhook, der sich weder mit dem Test- noch mit dem Live-Schlüssel entschlüsseln lässt, wird abgelehnt, sodass nur Peach Payments Ihre Bestellungen ändern kann. Ein mit dem Schlüssel eines Modus entschlüsselter Webhook wird nur auf Zahlungen angewendet, die in diesem Modus gestartet wurden. Das Modul verwendet Zahlungsbenachrichtigungen:
Andere Benachrichtigungen, etwa die Testbenachrichtigung beim Aktivieren des Webhooks, werden mit ignored beantwortet. Ohne den Webhook-Schlüssel wird eine Bestellung nur angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.
Payment form
Card brands: die Marken, die im Formular von Peach Payments angezeigt werden: Visa, Mastercard, American Express, Diners Club. Wählen Sie nur Marken aus, die für Ihre Entity ID aktiviert sind. Standard: Visa und Mastercard. Ist keine Marke ausgewählt, zeigt das Speichern eine Warnung, und das Formular zeigt Visa und Mastercard.
Advanced
Logging: protokolliert API-Anfragen und Zahlungsergebnisse in logs/peach_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web gelesen werden. Fehler und Warnungen werden immer protokolliert. Die Protokolle enthalten keine Kartendaten, Schlüssel oder Kundendaten. Standard: aus.
Log: zeigt die Größe und die neuesten Einträge des Protokolls. Klicken Sie auf Clear log, um es zu leeren.
Delete data on uninstall: ist die Option eingeschaltet, werden beim Deinstallieren des Moduls seine Einstellungen und Protokolle gelöscht. Die Peach Payments-Daten der Bestellungen (Checkout-Versuche, Zahlungs-IDs) und die Bestellstatus bleiben erhalten, weil sie zu den Bestellungen gehören. Standard: aus.
Checkout
Der Kunde wählt die Zahlungsart (standardmäßig Credit / Debit Card (Peach Payments)) und bestätigt die Bestellung. Im Testmodus zeigt die Zahlungsart Test mode: no real payment will be made. Das Modul bereitet einen Peach Payments-Checkout über die Warenkorbsumme in der Warenkorbwährung vor und zeigt die Seite Peach Payments payment Ihres Shops mit dem Kartenformular von Peach Payments und den gewählten Kartenmarken an, in der Sprache des Kunden, sofern Peach Payments sie unterstützt. Im Testmodus zeigt die Seite Test mode: use a Peach Payments test card, no real payment will be made. Die Kartendaten werden im Formular von Peach Payments eingegeben, und das Formularskript wird mit einem Subresource-Integrity-Hash geladen. Der Link Choose another payment method führt zurück zum Checkout. An diesem Punkt existiert noch keine Bestellung. Wenn die Seite neu geladen wird, wird derselbe Checkout bis zu 25 Minuten wiederverwendet, sofern sich der Warenkorb nicht geändert hat.
Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Peach Payments sie bestätigt: Der Shop liest das Ergebnis des Checkouts dieses Warenkorbs über die Peach Payments API aus, im Modus, in dem der Checkout erstellt wurde, und prüft, ob die Zahlung zu diesem Warenkorb gehört. Der Webhook macht dasselbe unabhängig davon; wer zuerst eintrifft, legt die Bestellung an, und die andere Meldung ändert nichts. Danach sieht der Kunde die übliche Bestellbestätigungsseite.
Wird die Zahlung nicht abgeschlossen, kehrt der Kunde mit einer Meldung zum Checkout zurück und kann es erneut versuchen: Payment failed: gefolgt vom Grund aus Peach Payments und Please try again or use another card., oder The payment was not completed. Please try again. Der Warenkorb bleibt erhalten. Kann das Ergebnis noch nicht bestätigt werden (etwa weil Peach Payments nicht geantwortet hat oder der Webhook genau in diesem Moment denselben Warenkorb verarbeitet), lautet die Meldung We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Ist für den Modus der Zahlung kein Webhook-Schlüssel gesetzt, wird der Kunde stattdessen gebeten, sich mit Ihnen in Verbindung zu setzen.
Kann das Zahlungsformular nicht vorbereitet werden, bleibt der Kunde im Checkout mit einer kurzen Meldung: The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (fehlende oder falsche Zugangsdaten), eine Meldung, dass einige Rechnungsdaten vom Zahlungsanbieter nicht akzeptiert wurden, oder The payment form could not be loaded. Please try again in a moment. Der technische Grund wird ins Protokoll geschrieben.
Der Webhook funktioniert auch, während der Shop im Wartungsmodus ist, und wird nicht durch die Ländersperre Ihres Shops blockiert.
Das Modul hat im Checkout-Schritt selbst kein Kartenformular, keine gespeicherten Karten, keine Abonnements, keine Vorautorisierung und Erfassung sowie keine EFT-, BNPL-, QR- oder anderen Zahlungsarten ohne Karte.
Bestellungen
Bestellstatus
No order yet: Der Kunde hat nicht bezahlt, die Zahlung wurde abgelehnt oder nicht abgeschlossen, oder Peach Payments hat sie noch nicht bestätigt. Es existiert nur der Warenkorb, und der Kunde kann erneut bezahlen.
Payment accepted: Die Zahlung wurde bestätigt, und Betrag und Währung stimmen mit dem Warenkorb überein. Die Zahlung wird mit der Zahlungs-ID von Peach Payments als Transaktions-ID erfasst; eine Notiz zeigt den Ergebniscode, die Beschreibung und die Zahlungs-ID von Peach Payments. Hat Peach Payments die Zahlung zur manuellen Prüfung markiert, fordert Sie die Notiz auf, sie vor dem Versand im Peach Payments-Dashboard zu prüfen.
Awaiting Peach Payments payment: Peach Payments hat eine Zahlung gemeldet, die auf eine Bestätigung wartet. Der Webhook setzt die Bestellung später auf Payment accepted oder markiert sie als fehlgeschlagen.
Peach Payments payment on hold: Der bezahlte Betrag oder die Währung weicht vom Warenkorb ab (Notiz amount/currency mismatch — manual review required), oder die Zahlung ist eingegangen, nachdem die Bestellung storniert worden war. Die Notiz erklärt, was zu prüfen ist. Prüfen Sie die Zahlung im Peach Payments-Dashboard und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.
Payment error: Peach Payments hat die Zahlung abgelehnt, auf die die wartende Bestellung gewartet hat. Ein abgelehnter Versuch ändert nie eine Bestellung, die bezahlt, auf Wartend gesetzt oder storniert ist.
Wenn eine zweite Zahlung für eine bereits bezahlte Bestellung erfolgreich ist, bleibt die Bestellung unverändert. Eine Notiz weist auf die doppelte Zahlung hin und bittet Sie, sie im Peach Payments-Dashboard zu erstatten. Eine Zahlung, die für eine erstattete Bestellung eingeht, wird nur auf der Bestellung vermerkt.
Peach Payments-Zahlungsblock
Die Bestellseite zeigt einen Block Peach Payments payment mit der Zahlungs-ID, der Checkout-ID, der Händler-Transaktions-ID, dem an Peach Payments gesendeten Betrag, dem Ergebnis und Ergebniscode, einem Abzeichen Test mode für Testzahlungen und den Peach Payments notes der Bestellung.
Erstattungen
Erstattungen über die PrestaShop-Bestellseite sind nicht verfügbar. Erstatten Sie die Zahlung im Peach Payments-Dashboard und erfassen Sie sie bei Bedarf in PrestaShop (Teilerstattung oder Gutschriftsbeleg). Ist der Webhook eingerichtet, werden Erstattungen, Stornierungen und Chargebacks, die in Peach Payments vorgenommen werden, mit Betrag und ID in den Bestellnotizen ergänzt; der Bestellstatus wird nicht geändert.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Peach Payments Pay Gateway ist der erste Block unter Modules > Module Manager > VibeFox Peach Payments Pay Gateway > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den Schlüssel maskiert, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-peach und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. Die Texte des Blocks folgen der Sprache des Back-Office (Englisch und Russisch sind enthalten).
Wird der Schlüssel nicht akzeptiert, nennt der Block den Grund, zum Beispiel Key not found, This key belongs to another product, Domain limit reached oder License expired on mit einem Datum. Nach einer Änderung der Shop-Adresse oder nachdem Sie einen Domain-Platz in Ihrem Konto freigegeben haben, klicken Sie auf Check now. Kann der Lizenzserver nicht erreicht werden, arbeitet das Modul mit dem zuletzt bekannten Status weiter.
Ein Schlüssel gilt für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt den Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.
Ohne aktiven Schlüssel wird Peach Payments Kunden im Checkout nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Der Kundenbereich von PrestaShop erkennt nicht, dass Sie im Back-Office angemeldet sind, daher wird die Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht im Checkout testen. Ein Hinweis erscheint in Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin durch die Rückkehr des Kunden und den Webhook bestätigt.
Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support benötigen jedoch eine Verlängerung. Der Status wird während der Arbeit im Back-Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach der Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.
Fehlerbehebung
Peach Payments erscheint nicht im Checkout: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, Entity ID und Access Token des aktuellen Modus eingetragen sind (Test Entity ID und Test Access Token im Testmodus, Live Entity ID und Live Access Token im Livemodus) und die Warenkorbwährung ZAR, KES oder MUR ist. Die Hinweise oben in den Einstellungen nennen das Problem. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.
Die Zahlung war erfolgreich, aber es wurde keine Bestellung angelegt: Der Kunde ist nicht in den Shop zurückgekehrt, und der Webhook ist nicht eingegangen. Prüfen Sie, ob Peach Payments Card-Webhooks genau für die in den Einstellungen angezeigte URL aktiviert hat, ob der Webhook Decryption Key des Modus eingetragen ist, in dem die Zahlung erfolgte, und ob keine Firewall oder Passwortschutz die URL blockiert. Aktivieren Sie Logging und prüfen Sie das Feld Log auf abgelehnte Webhooks.
Der Webhook antwortet Decryption failed: Der Webhook konnte weder mit dem Test- noch mit dem Live-Schlüssel entschlüsselt werden. Der Schlüssel ist falsch oder gehört zu einem anderen Konto oder Modus. Geben Sie den Schlüssel ein, den Peach Payments für diese Webhook-URL gesendet hat.
Der Webhook antwortet Webhook key not configured: Weder der Test- noch der Live-Webhook-Schlüssel ist gesetzt oder gültig. Geben Sie den 64-stelligen Schlüssel ein. Peach Payments sendet den Webhook später erneut.
Der Webhook antwortet Busy, retry later: Der Warenkorb wurde im selben Moment durch die Rückkehr des Kunden verarbeitet, oder die Bestellung konnte nicht angelegt werden (etwa weil das Modul deaktiviert ist). Es wurde nichts verändert, und Peach Payments sendet den Webhook erneut. Das Protokoll zeigt den Grund.
Der Webhook antwortet Missing or malformed data: Die Anfrage enthielt keinen verschlüsselten Inhalt oder die Header X-Initialization-Vector / X-Authentication-Tag, etwa weil ein Proxy die Anfrage verändert hat. Es wurde nichts verändert.
Der Webhook antwortet ignored: Die Benachrichtigung ist echt, gehört aber nicht zu einem Checkout dieses Shops (anderer Shop mit derselben Entity ID, gelöschter Warenkorb) oder stammt aus einem anderen Modus als die Zahlung. Es wurde nichts verändert.
Die Webhook-URL zeigt im Browser Method not allowed: Das ist normal. Die URL akzeptiert nur Anfragen von Peach Payments.
Der Kunde sieht The payment form is not available right now: Access Token oder Entity ID des aktuellen Modus sind falsch. Prüfen Sie die Zugangsdaten und den Modus und lesen Sie im Protokoll den Peach Payments-Code.
Die Bestellung steht nach der Zahlung auf Peach Payments payment on hold: Lesen Sie die Notizen im Block Peach Payments payment. Der bezahlte Betrag oder die Währung wich vom Warenkorb ab, oder die Zahlung ist eingegangen, nachdem die Bestellung storniert worden war. Prüfen Sie die Zahlung im Peach Payments-Dashboard und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.
Beim Speichern erscheint die Meldung, dass der Webhook-Schlüssel der 64-stellige hexadezimale Schlüssel sein muss: Der Wert ist nicht der Schlüssel von Peach Payments. Webhooks können erst entschlüsselt werden, wenn er korrigiert ist.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Peach Payments Pay Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall eingeschaltet, werden die Moduleinstellungen und Protokolle entfernt. Ist die Option ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Checkout-Versuche, Zahlungs-IDs und die Bestellstatus Awaiting Peach Payments payment und Peach Payments payment on hold bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Transaktions-IDs und Peach Payments-Checkout-Daten.
Peach Payments ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Peach Payments verbunden und wird nicht von Peach Payments unterstützt.