VibeFox OpenPay for OpenCart — Hilfe

Anforderungen

OpenCart: 3.0.x (getestet mit 3.0.5.0) oder 4.0.2 und neuer (getestet mit 4.1.0.3).

PHP: 8.0 oder neuer.

HTTPS: Ihr Shop muss HTTPS verwenden, da sich das Kartenformular auf Ihrer Kassenseite befindet.

OpenPay account: ein OpenPay-Konto aus Mexiko, Kolumbien oder Peru. Sie benötigen dessen Merchant ID, den privaten Schlüssel (sk_...) und den öffentlichen Schlüssel (pk_...). Die Sandbox- und die Produktiv-Dashboards haben unterschiedliche Merchant IDs und Schlüssel, und die Erweiterung hält sie getrennt.

Currency: Der Kunde muss in einer Währung bezahlen, die das Land Ihres Kontos akzeptiert: Mexiko — MXN oder USD, Kolumbien — COP oder USD, Peru — PEN oder USD. Bei anderen Währungen wird die Zahlungsmethode an der Kasse ausgeblendet.

VibeFox license key: Erwerb auf vibefox.net. Ein Schlüssel funktioniert für eine Domain.

Die Karte wird auf Ihrer Kassenseite eingegeben, jedoch im Browser von openpay.js gelesen und tokenisiert. Die Kartenfelder haben keinen Namen und werden niemals an Ihren Server gesendet. Da sich das Kartenformular auf Ihrer Seite befindet, lautet Ihr PCI-DSS-Umfang SAQ A-EP; fragen Sie Ihren Acquirer.

Installation

Der Download ist eine ZIP-Datei mit den Paketen für beide OpenCart-Versionen. Entpacken Sie sie auf Ihrem Computer. Sie enthält README.txt, das Paket für OpenCart 3 wcp_openpay_gateway-oc3-(version).ocmod.zip und das Paket für OpenCart 4 wcp_openpay_gateway.ocmod.zip. Installieren Sie nur das Paket für Ihre OpenCart-Version. Der Lizenzschlüssel ist für beide Versionen gleich.

OpenCart 3

1. Gehen Sie im Admin-Bereich zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_openpay_gateway-oc3-(version).ocmod.zip. Die Erweiterung enthält keine OCMOD-Änderungen, daher muss Extensions > Modifications nicht aktualisiert werden. Statt des Installers können Sie auch den Inhalt des Ordners upload aus diesem Paket in das Stammverzeichnis Ihres Shops kopieren.

2. Gehen Sie zu Extensions > Extensions und wählen Sie den Typ Payments. Suchen Sie VibeFox OpenPay Gateway und klicken Sie auf Install (die grüne +-Schaltfläche). Ihr Admin-Benutzer benötigt das Recht, die Liste der Zahlungserweiterungen zu ändern.

3. Klicken Sie auf Edit (die Stift-Schaltfläche), um die Einstellungsseite zu öffnen. Fügen Sie Ihren VibeFox-Lizenzschlüssel in License key im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Wählen Sie das Account country und geben Sie die Sandbox- und die Live-Schlüssel ein (siehe Konfiguration).

5. Empfohlen: Fügen Sie die Webhook-URL im OpenPay-Dashboard hinzu (siehe Konfiguration).

6. Aktivieren Sie Enable / Disable und klicken Sie auf Save. Testen Sie eine Zahlung mit den Testkarten der OpenPay-Sandbox und deaktivieren Sie dann Sandbox mode, um echte Zahlungen anzunehmen. Behalten Sie die Sandbox-Schlüssel, solange Sie Sandbox-Bestellungen noch erstatten müssen.

OpenCart 4

1. Gehen Sie im Admin zu Extensions > Installer, klicken Sie auf Upload und wählen Sie die Datei wcp_openpay_gateway.ocmod.zip. Benennen Sie die Datei nicht um: OpenCart 4 entnimmt den Code der Erweiterung dem Dateinamen, und ein umbenanntes Paket funktioniert nicht.

2. Das Paket erscheint auf derselben Seite in der Liste der installierten Erweiterungen. Klicken Sie daneben auf Install (die grüne +-Schaltfläche).

3. Gehen Sie zu Extensions > Extensions und wählen Sie den Typ Payments. Suchen Sie VibeFox OpenPay Gateway, klicken Sie auf Install (die grüne +-Schaltfläche) und danach auf Edit (die Stift-Schaltfläche).

4. Geben Sie den Lizenzschlüssel, die OpenPay-Schlüssel und den Webhook ein wie in den Schritten 3 bis 6 für OpenCart 3. Die Einstellungsseite und ihre Felder sind in beiden Versionen gleich. Nur die Webhook-URL ist anders (siehe Webhook).

Eine neue Installation startet mit deaktivierter Zahlungsmethode und aktiviertem Sandbox-Modus.

Konfiguration

Alle Einstellungen befinden sich auf der Seite der Erweiterung: Extensions > Extensions > Payments > VibeFox OpenPay Gateway > Edit. Die Abschnitte sind links aufgelistet; die Schaltfläche Save unter der Liste speichert die gesamte Seite. Oberhalb der Einstellungen warnt die Seite, wenn die Schlüssel des aktuellen Modus unvollständig sind (die Zahlungsmethode wird dann an der Kasse ausgeblendet) und wenn die Standardwährung Ihres Shops vom gewählten Land des Kontos nicht akzeptiert wird. Solange der Sandbox-Modus aktiv ist, wird außerdem Sandbox mode is enabled — no real charges are made. angezeigt. Ohne das Recht, die Erweiterung zu ändern, zeigt die Seite die Einstellungen an, kann sie aber nicht speichern.

Beim Speichern werden die Schlüssel geprüft. Eine Merchant ID darf nur Buchstaben und Ziffern enthalten, ein privater Schlüssel muss mit sk_ und ein öffentlicher Schlüssel mit pk_ beginnen. Ein ungültiger Wert wird nicht gespeichert: Der bisherige Wert bleibt erhalten und es erscheint eine Fehlermeldung, zum Beispiel Sandbox: The private key must start with sk_. Dasselbe gilt für eine Sort Order, die keine ganze Zahl ist (Sort Order must be a whole number — the previous value was kept.), und für einen Total-Wert, der keine Zahl von 0 oder mehr ist. Die übrigen Felder werden gespeichert. Ist die Zahlungsmethode aktiviert, die Schlüssel des aktuellen Modus aber unvollständig, sehen Sie außerdem einen Hinweis, dass das Gateway an der Kasse ausgeblendet bleibt. Ein leerer Title oder einer mit mehr als 128 Zeichen wird mit Enter a title for the payment method (1 to 128 characters). abgelehnt, und dann wird nichts gespeichert.

OpenPay

Enable / Disable: Enable OpenPay card payments schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Er wird außerdem als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: Credit or debit card (OpenPay). Erforderlich, bis zu 128 Zeichen.

Description: der Text, der im Schritt Confirm Order über dem Kartenformular angezeigt wird. Standard: Pay securely with your credit or debit card. Ihre Bank kann die Zahlung bestätigen lassen (3D Secure).

Sort Order: die Position von OpenPay unter den Zahlungsmethoden an der Kasse. Lassen Sie das Feld leer oder geben Sie eine ganze Zahl ein (negative Zahlen sind erlaubt).

Geo Zone: OpenPay nur für Zahlungsadressen in der gewählten Geozone anbieten. Standard: All zones. Geozonen werden unter System > Localisation > Geo Zones eingerichtet. In OpenCart 4 wird die Lieferadresse verwendet, wenn der Shop keine Zahlungsadresse abfragt.

Total: der Warenkorbbetrag in der Standardwährung des Shops, den eine Bestellung erreichen muss, bevor OpenPay angeboten wird. Lassen Sie das Feld leer, um OpenPay bei jedem Betrag anzubieten.

OpenPay-Konto

Merchant ID, privater Schlüssel (sk_) und öffentlicher Schlüssel (pk_) finden Sie in Ihrem OpenPay-Dashboard unter Settings (Configuración). Der Abschnitt enthält Links zu den Sandbox- und Produktiv-Dashboards von Mexiko, Kolumbien und Peru.

Account country: das Land Ihres OpenPay-Kontos. Es bestimmt die OpenPay-API, die openpay.js-Bibliothek dieses Landes und die akzeptierten Währungen. Standard: Mexico.

Sandbox mode: verwendet die OpenPay-Sandbox (Testschlüssel, keine echten Belastungen) und schaltet sowohl die Schlüssel als auch die API auf die Sandbox um. Während er aktiv ist, wird an der Kasse ein Hinweis SANDBOX MODE angezeigt. Standard: an. Deaktivieren Sie ihn, um echte Zahlungen anzunehmen.

Sandbox Merchant ID: die Merchant ID aus dem Sandbox-Dashboard, Settings (Configuración), API-Schlüssel.

Sandbox Private Key: der private Sandbox-Schlüssel. Er beginnt mit sk_. Er wird nur auf dem Server verwendet; geben Sie ihn niemals weiter.

Sandbox Public Key: der öffentliche Sandbox-Schlüssel. Er beginnt mit pk_. openpay.js verwendet ihn im Browser, um die Karte zu tokenisieren.

Live Merchant ID: die Merchant ID aus dem Produktiv-Dashboard, Settings (Configuración), API-Schlüssel.

Live Private Key: der private Produktivschlüssel (sk_...).

Live Public Key: der öffentliche Produktivschlüssel (pk_...).

Gespeicherte private Schlüssel werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. an. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten. Um einen gespeicherten privaten Schlüssel zu entfernen, setzen Sie unter dem Feld den Haken bei Clear the saved key on save und klicken Sie auf Save.

Webhook

Der Webhook ist nicht zwingend erforderlich, wird aber empfohlen. Er bestätigt Zahlungen, wenn der Kunde nach der 3D-Secure-Seite nicht zurückkehrt, zum Beispiel nachdem er den Browser geschlossen hat. Gehen Sie im OpenPay-Dashboard zu Settings > Webhooks und fügen Sie die URL hinzu, die in diesem Abschnitt unter Webhook URL angezeigt wird. Bei OpenCart 3 hat sie die Form https://your-store/index.php?route=extension/payment/wcp_openpay_gateway/webhook, bei OpenCart 4 die Form https://your-store/index.php?route=extension/wcp_openpay_gateway/payment/wcp_openpay_gateway.webhook. Sie wird aus der Storefront-Adresse Ihrer OpenCart-Installation gebildet. Kopieren Sie sie genau so, wie die Einstellungen sie anzeigen. Fügen Sie den Webhook im Dashboard jedes von Ihnen verwendeten Modus hinzu (Sandbox und Produktiv).

Wenn Sie den Webhook hinzufügen, sendet OpenPay einen Verifizierungscode an diese URL. Der Code erscheint in diesem Abschnitt mit dem Datum des Eingangs, sodass Sie den Webhook im OpenPay-Dashboard bestätigen können. Bis dahin zeigt der Abschnitt No verification code received yet. an.

Die Erweiterung verarbeitet diese Ereignisse:

OpenPay signiert Webhooks nicht, daher vertraut die Erweiterung der Benachrichtigung selbst nie. Sie nutzt sie nur, um die Belastung zu finden, und liest die Belastung anschließend über die OpenPay-API mit dem privaten Schlüssel des Modus und des Kontolandes, in dem die Zahlung erfolgte. Eine Benachrichtigung zu einer Belastung, die dieser Shop nicht angelegt hat, wird ignoriert. Der Webhook funktioniert auch, wenn sich der Shop im Wartungsmodus befindet: OpenCart 3 lässt Anfragen von Zahlungserweiterungen durch, und bei OpenCart 4 fügt die Erweiterung eine Startaktion hinzu, die den Webhook und die Rückkehr des Kunden von 3D Secure durchlässt.

Bestellungen

OpenCart legt die Bestellung im Schritt Confirm Order ohne Status an (eine fehlende Bestellung). Die Bestellung erhält erst dann einen Status, nachdem OpenPay die Belastung bestätigt hat. Eine abgelehnte Karte oder eine fehlgeschlagene 3D-Secure-Prüfung lässt die Bestellung ohne Status, eine Notiz erklärt den Grund, und der Kunde kann erneut bezahlen. Jedes der folgenden Felder listet Ihre OpenCart-Bestellstatus auf; eigene Status können Sie unter System > Localisation > Order Statuses anlegen.

Order Status After Payment: OpenPay hat die Belastung bestätigt und Betrag sowie Währung stimmen mit der Bestellung überein. Standard: Processing.

Awaiting OpenPay Payment: die Belastung läuft noch (noch nicht eingezogen); der Webhook schließt sie später ab oder setzt sie auf fehlgeschlagen. Standard: Pending.

OpenPay Payment On Hold: OpenPay hat einen anderen Betrag oder eine andere Währung belastet als in der Bestellung angegeben, oder eine Belastung wurde abgeschlossen, nachdem die Bestellung storniert worden war. Standard: Pending.

Payment Error Status: die Belastung einer Bestellung, die auf OpenPay wartet, oder einer zurückgehaltenen Bestellung ist fehlgeschlagen, wurde abgebrochen oder ist abgelaufen. Standard: Failed.

Refunded Status: die Belastung wird von der Bestellseite aus vollständig erstattet. Teilerstattungen fügen nur eine Notiz hinzu. Standard: Refunded.

Erweitert

Debug log: protokolliert die Schritte der Zahlung in wc_opy_debug.log.php im Logs-Ordner von OpenCart (storage/logs). Die Datei lässt sich nicht über das Web öffnen; bei 5 MB wird sie nach wc_opy_debug.old.log.php verschoben. Fehler und Warnungen werden auch dann protokolliert, wenn die Option aus ist. Schlüssel, Kartendaten und Kundendaten werden nie protokolliert. Standard: aus.

Log: zeigt die Größe und die neuesten Einträge des Protokolls an. Klicken Sie auf Clear log, um es zu leeren.

Delete data on uninstall: ist die Option aktiviert, entfernt das Deinstallieren der Erweiterung die Gateway-Einstellungen, den gespeicherten Verifizierungscode des Webhooks und das Protokoll. Die OpenPay-Belastungsdaten der Bestellungen gehören zur Zahlungshistorie und bleiben immer erhalten, sodass Bestellungen auch nach einer erneuten Installation erstattet werden können. Standard: aus.

Import / Export

Export: Download JSON speichert die Einstellungen als JSON-Datei. Private Schlüssel werden nicht exportiert.

Import: fügen Sie zuvor exportiertes JSON ein und klicken Sie auf Import, um die Einstellungen wiederherzustellen. Gespeicherte private Schlüssel bleiben erhalten.

Kasse

Im Schritt Payment Method wählt der Kunde die Zahlungsmethode (standardmäßig Credit or debit card (OpenPay)). Im Schritt Confirm Order sieht der Kunde Ihre Beschreibung und das Kartenformular: Cardholder name, Card number, Expiry (MM/YY) und Card code (CVV). Im Sandbox-Modus zeigt das Formular SANDBOX MODE — Test environment. No real charges will be made. an. OpenCart legt die Bestellung in diesem Schritt an, noch ohne Status. Bei OpenCart 4 wählt der Kunde die Zahlungsart mit dem Button Choose im Block der Zahlungsart, im Fenster Payment method options; das Kartenformular steht im Bestätigungsbereich unten auf der Kassenseite, oberhalb von Confirm Order. Wenn der Kunde auf Confirm Order klickt, wandelt openpay.js die Karte im Browser in ein Einmal-Token um, und die Antifraud-Bibliothek fügt eine Geräte-Sitzungs-ID hinzu. Nur diese zwei Werte werden an Ihren Shop gesendet. Ein unvollständiges Formular zeigt Please fill in all card fields. unter dem Formular an.

Die Erweiterung erstellt anschließend die Belastung mit 3D Secure für den Bestellbetrag in der Bestellwährung und schickt den Kunden auf die von OpenPay bereitgestellte 3D-Secure-Seite seiner Bank. Jeder Versuch erhält eine eigene OpenPay-Bestellreferenz. Die Belastungsbeschreibung lautet Order #, die Bestellnummer und der Name Ihres Shops. Name, E-Mail-Adresse und Telefonnummer des Kunden aus der Zahlungsadresse werden an OpenPay übergeben; es wird kein OpenPay-Kundenkonto angelegt.

Wenn der Kunde zurückkehrt, liest die Erweiterung die Belastung über die OpenPay-API aus. Die Bestellung wird erst als bezahlt markiert, wenn OpenPay dies bestätigt: Die Belastung muss zu dieser Bestellung gehören, abgeschlossen sein und Betrag sowie Währung der Bestellung exakt entsprechen. Die Bestellung erhält dann ihren Status auf die übliche OpenCart-Weise, mit den üblichen Bestell-E-Mails und der Bestandsaktualisierung, und der Kunde sieht die Erfolgsseite von OpenCart mit Your card payment has been received. Meldet OpenPay die Belastung als laufend, erhält die Bestellung den Status Awaiting OpenPay Payment, und die Seite zeigt We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Ist das Ergebnis noch nicht bekannt, zeigt eine Seite Payment confirmation denselben Text mit einer Schaltfläche Check again und einer Schaltfläche Back to checkout; sobald der Webhook eintrifft, setzt er den Bestellstatus. Schlägt eine laufende Belastung später fehl, zeigt die Erfolgsseite Your OpenPay card payment was not completed. Please contact us about this order.

Wird die Karte abgelehnt oder schlägt 3D Secure fehl, bleibt die Bestellung ohne Status, eine Notiz wird hinzugefügt, und der Kunde kehrt zur Kasse zurück, wo The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. steht. Der Warenkorb bleibt erhalten. Bei OpenCart 4 werden diese Meldungen oberhalb der Kassenseite angezeigt. OpenCart 3 legt jedes Mal eine neue Bestellung an, wenn der Schritt Confirm Order angezeigt wird; OpenCart 4 behält eine Bestellung für die Kasse und aktualisiert sie, sodass der Kunde dieselbe Bestellung mit einem neuen Versuch erneut bezahlt. Vor einem neuen Versuch prüft die Erweiterung die vorherige Belastung des Warenkorbs: Wurde sie tatsächlich bezahlt, erhält diese Bestellung ihren Status, ohne dass ein zweites Mal belastet wird; ist sie noch in Bearbeitung, sieht der Kunde A previous payment for this order is still being processed. Please do not pay again — the order will be updated automatically.; kann ihr Status nicht geprüft werden, erfolgt keine neue Belastung, und der Kunde sieht We could not confirm the status of your previous payment attempt. Please try again in a few minutes. Ein bereits bezahlter Warenkorb wird niemals erneut belastet.

Bei OpenCart 4 bleibt die Bestellung in der Kasse, bis die Erfolgsseite angezeigt wird. Wurde diese Bestellung inzwischen geschlossen (zum Beispiel weil ihre Belastung fehlschlug, nachdem sie auf Zahlung wartete, oder weil Sie sie storniert oder erstattet haben), wird der Kunde mit This order can no longer be paid. Please reload the checkout page and confirm the order again. zurück zur Kasse geschickt, und das nächste Confirm Order bezahlt eine neue Bestellung. Hat diese Bestellung bereits einen Status und enthält der Warenkorb nun andere Produkte oder Mengen, wird der Kunde ebenfalls zurück zur Kasse geschickt, und der neue Warenkorb erhält eine neue Bestellung.

Abgelehnte Karten erhalten eine klare Meldung, zum Beispiel The card has insufficient funds. Please use another card., The card has expired. Please use another card. oder The security code (CVV) is not valid. Please check it and try again. Technische Fehler von OpenPay werden Kunden nie angezeigt; sie gehen in das Protokoll und in die Bestellnotizen.

Die Zahlungsmethode wird an der Kasse ausgeblendet, wenn sie deaktiviert ist, wenn die Schlüssel des aktuellen Modus unvollständig sind oder wenn der Kunde in einer Währung zahlt, die das Land des Kontos nicht akzeptiert.

Die Erweiterung nimmt nur Kartenzahlungen an, die sofort eingezogen werden. Sie unterstützt keine gespeicherten Karten, Abonnements, zinsfreie Monatsraten (MSI) oder Ratenzahlungen, Zahlungen mit Kartenpunkten, Barzahlungen, SPEI-, PSE- oder CoDi-Zahlungen und keine getrennte Autorisierung und Erfassung.

Bestellungen und Erstattungen

Bestellstatus

No status (missing order): Der Kunde befindet sich auf der 3D-Secure-Seite, hat die Zahlung nicht abgeschlossen oder die Karte wurde abgelehnt. Unter Sales > Orders werden solche Bestellungen nur angezeigt, wenn der Filter Order Status auf Missing Orders gesetzt ist.

Eine unbezahlte Bestellung aus der Kasse kann bei OpenCart 4 den Status Voided erhalten, den OpenCart 4 setzt, wenn der Kunde zum Schritt Confirm Order zurückkehrt. Die Erweiterung behandelt eine solche Bestellung als Bestellung ohne Status, und eine spätere Zahlung bestätigt sie trotzdem.

Order Status After Payment (default Processing): die Zahlung wurde bestätigt. Eine Notiz zeigt die OpenPay-Belastungs-ID und den Modus (Produktiv oder Sandbox).

Awaiting OpenPay Payment (default Pending): OpenPay meldet die Belastung als laufend (noch nicht eingezogen). Die Bestellung wechselt zu Order Status After Payment, sobald die Belastung abgeschlossen ist, oder zu Payment Error Status, wenn sie fehlschlägt.

OpenPay Payment On Hold (default Pending): OpenPay meldet eine abgeschlossene Belastung mit einem anderen Betrag oder einer anderen Währung als in der Bestellung (die Bestellung wird nicht als bezahlt markiert, die Notiz zeigt die Differenz), oder eine Zahlung ist für eine bereits stornierte oder erstattete Bestellung eingegangen. Prüfen Sie die Bestellung und bearbeiten Sie sie oder erstatten Sie die Zahlung.

Payment Error Status (default Failed): eine laufende Belastung ist fehlgeschlagen, wurde abgebrochen oder ist abgelaufen.

Refunded Status (default Refunded): die Belastung wurde über die Erweiterung vollständig erstattet.

Geht für eine bereits bezahlte Bestellung oder einen bereits bezahlten Warenkorb eine zweite abgeschlossene Belastung ein, bleibt die Bestellung unverändert. Eine Notiz, die mit OpenPay WARNING beginnt, weist auf der bezahlten Bestellung darauf hin, dass Sie die doppelte Belastung im OpenPay-Dashboard erstatten sollten.

Notizen sind Einträge in der History der Bestellung, die der Kunde nicht sieht.

Reiter VibeFox OpenPay Gateway

Öffnen Sie unter Sales > Orders eine mit OpenPay bezahlte Bestellung. Unten auf der Bestellseite, neben History und Additional, zeigt der Reiter VibeFox OpenPay Gateway die Belastungs-ID, den Belastungsstatus, die Umgebung und das Kontoland mit der Kennzeichnung Sandbox bei Sandbox-Zahlungen, die Beträge Charged / order, den erstatteten Betrag, das Erstattungsformular, den Erstattungsverlauf und die OpenPay notes der Bestellung. Der Reiter ist für Benutzer sichtbar, die Zugriff auf die Erweiterung haben.

Erstattungen

Bei Konten aus Mexiko und Peru: Geben Sie im Reiter den Amount ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Reason (optional), und klicken Sie auf Refund via OpenPay. Bestätigen Sie die Abfrage Refund this amount through OpenPay? This cannot be undone. Vollständige und Teilerstattungen werden unterstützt, bis zu dem Betrag, den OpenPay belastet hat. Sie benötigen das Recht, die Erweiterung zu ändern (festgelegt unter System > Users > User Groups). Die Erstattung wird mit den Schlüsseln des Modus und des Kontolandes gesendet, in dem die Belastung erfolgte; diese Schlüssel müssen daher eingerichtet sein. Akzeptiert OpenPay die Erstattung nicht, zeigt der Reiter den Fehler an, zum Beispiel OpenPay refund failed: ..., und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit der OpenPay-Erstattungs-ID dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded Status, ohne den Kunden zu benachrichtigen und ohne Artikel wieder in den Bestand zurückzubuchen, genau wie eine manuelle Statusänderung. Eine Teilerstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald OpenPay die Zahlung bestätigt hat; eine Bestellung, die nach einer Betragsabweichung zurückgehalten wird, wird nicht über die Erweiterung erstattet.

OpenPay Colombia unterstützt Kartenerstattungen über die API nicht, wie auch in den offiziellen OpenPay-Integrationen. Für kolumbianische Belastungen bietet der Reiter kein Erstattungsformular an und erklärt den Grund; erstatten Sie die Belastung im OpenPay-Dashboard.

Produktrücksendungen unter Sales > Returns erstatten kein Geld über OpenPay.

Erstattungen und Chargebacks, die im OpenPay-Dashboard vorgenommen werden, werden per Webhook übermittelt und einmalig den Notizen hinzugefügt. Der Bestellstatus ändert sich dabei nicht automatisch. Aktualisieren Sie ihn bei Bedarf manuell.

Lizenzschlüssel

Die Erweiterung arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox OpenPay Gateway ist der erste Block unter Extensions > Extensions > Payments > VibeFox OpenPay Gateway > Edit, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: opencart-payment-openpay und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Admin-Benutzer mit der Berechtigung Modify für die Erweiterung können den Schlüssel ändern. Die Texte des Blocks folgen der Admin-Sprache (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 in Ihrem Konto einen Domain-Platz freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet die Erweiterung mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert für eine Domain: die Shop-Adresse aus der OpenCart-Konfiguration. Das Entfernen des Schlüssels aus dem Shop gibt seinen Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne einen aktiven Schlüssel wird OpenPay Kunden an der Kasse nicht angezeigt. Wird dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Ein Admin-Benutzer, der im Admin-Bereich im selben Browser angemeldet ist, sieht die Zahlungsmethode weiterhin im Shop, markiert mit (unlicensed — visible to admins only), sodass Sie die Erweiterung einrichten und testen können, bevor Sie einen Schlüssel kaufen. Bei OpenCart 4 ist diese Vorschau nicht verfügbar: Der Shop sieht die Anmeldung im Admin nicht, daher wird die Zahlungsmethode ohne aktiven Schlüssel für alle ausgeblendet. Nachdem Sie die Seite Edit einmal geöffnet haben, erscheint ein Hinweis auf dem Dashboard im Admin-Bereich. Schließen Sie ihn mit ×, um ihn für 7 Tage auszublenden. Bestehende Bestellungen bleiben unberührt: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet die Erweiterung weiter, Updates und Support benötigen aber eine Verlängerung. Der Status wird automatisch erneut geprüft, wenn Sie das Dashboard oder die Seite Edit im Admin-Bereich öffnen: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Beim Deinstallieren der Erweiterung werden Lizenzschlüssel und Lizenzstatus immer entfernt.

Fehlerbehebung

OpenPay erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist und der aktuelle Modus alle drei Schlüssel hat: die Sandbox-Schlüssel im Sandbox-Modus, die Live-Schlüssel im Live-Modus. Prüfen Sie, ob der Kunde in einer Währung zahlt, die vom Account country akzeptiert wird (Mexiko: MXN, USD; Kolumbien: COP, USD; Peru: PEN, USD). Die Einstellungsseite zeigt in jedem dieser Fälle eine Warnung. Prüfen Sie außerdem, ob die Zahlungsadresse in der gewählten Geo Zone liegt und ob die Bestellung den in den Einstellungen festgelegten Total-Betrag erreicht.

Die Zahlung ist erfolgt, aber die Bestellung bleibt ohne Status: Der Kunde ist nicht von der 3D-Secure-Seite zurückgekehrt, und der Webhook funktioniert nicht. Prüfen Sie, ob die Webhook-URL im OpenPay-Dashboard des von Ihnen verwendeten Modus hinzugefügt ist, genau so, wie die Einstellungen sie anzeigen, mit den oben aufgeführten Ereignissen. Prüfen Sie, ob die Schlüssel des Modus, in dem die Zahlung erfolgte, ausgefüllt sind: Ohne sie antwortet der Webhook not configured, und OpenPay versucht es später erneut. Die Bestellung erhält ihren Status auch, wenn der Kunde zum Shop zurückkehrt oder versucht, denselben Warenkorb erneut zu bezahlen.

Der Webhook antwortet ignored (unknown order): Die Belastung wurde nicht von diesem Shop angelegt, zum Beispiel eine Belastung eines anderen Shops auf demselben OpenPay-Konto. Es wird nichts geändert.

Der Webhook antwortet verification failed: Die OpenPay-API konnte zum Lesen der Belastung nicht erreicht werden. OpenPay wiederholt den Webhook.

Der Webhook antwortet busy: Der Warenkorb wurde gerade von einer anderen Anfrage aktualisiert, oder der Bestellstatus konnte nicht gesetzt werden. OpenPay wiederholt den Webhook. Aktivieren Sie Debug log, um den Grund zu sehen.

Die Webhook-URL zeigt im Browser invalid body: Das ist normal. Die URL akzeptiert nur Benachrichtigungen von OpenPay.

Der Kunde sieht The secure card form could not be loaded: openpay.js oder die Antifraud-Bibliothek von OpenPay wurde im Browser nicht geladen, oder die Geräte-Sitzungs-ID konnte nicht erstellt werden. Bitten Sie den Kunden, die Seite neu zu laden und es erneut zu versuchen.

Der Kunde sieht The payment could not be processed right now: OpenPay hat die Anfrage abgelehnt oder nicht geantwortet. Der Grund steht im Protokoll und in den Bestellnotizen. Eine falsche Merchant ID oder ein falscher privater Schlüssel ist eine typische Ursache. Hat OpenPay nicht geantwortet, prüfen Sie die Belastung im OpenPay-Dashboard, bevor der Kunde erneut bezahlt.

Der Kunde sieht This test card cannot be used for real payments: Es wurde eine Sandbox-Testkarte verwendet, während der Sandbox-Modus deaktiviert ist.

Der Kunde sieht Billing email is required for OpenPay: Die Bestellung hat keine gültige E-Mail-Adresse.

Die Bestellung hat nach der Zahlung den Status OpenPay Payment On Hold: Lesen Sie die OpenPay notes im Reiter (siehe Bestellstatus) und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Die Erstattung schlägt mit einer Meldung zum Modus fehl: Die Bestellung wurde im Sandbox- oder im Live-Modus bezahlt, und die Schlüssel dieses Modus sind nicht eingerichtet. Geben Sie sie ein und versuchen Sie es erneut.

Die Erstattung schlägt mit The order is being updated right now fehl: Ein Webhook oder eine andere Anfrage hat die Bestellung im selben Moment aktualisiert. Versuchen Sie es in einem Moment erneut.

Deinstallation

Gehen Sie zu Extensions > Extensions, wählen Sie den Typ Payments und klicken Sie neben VibeFox OpenPay Gateway auf Uninstall (die rote −-Schaltfläche). Lizenzschlüssel und Lizenzstatus dieser Erweiterung werden immer entfernt. OpenCart entfernt immer die eigenen Einstellungen der Erweiterung: Enable / Disable, Sort Order, Geo Zone, Total sowie die Bestellstatus aus dem Bereich Orders, die bei einer erneuten Installation auf ihre Standardwerte zurückgesetzt werden. Auch das OpenCart-Ereignis der Erweiterung wird entfernt (bei OpenCart 4 seine Ereignisse und seine Startaktion, die den Webhook und die Rückkehr von 3D Secure im Wartungsmodus durchlässt). Ist Delete data on uninstall aktiviert, werden die übrigen Gateway-Einstellungen (Titel, Beschreibung, Kontoland, Sandbox-Modus, Schlüssel, Protokollierung), der gespeicherte Verifizierungscode des Webhooks und das Protokoll entfernt. Ist die Option deaktiviert, bleiben sie für eine spätere Neuinstallation erhalten. Die Belastungs- und Erstattungsdaten von OpenPay bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation noch erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen.

Bei OpenCart 4 entfernen Sie außerdem die Dateien der Erweiterung: Gehen Sie nach der Deinstallation zu Extensions > Installer und klicken Sie in der Liste der installierten Erweiterungen neben VibeFox OpenPay Gateway auf Uninstall (die orangefarbene −-Schaltfläche) und danach auf Delete (die rote Papierkorb-Schaltfläche), um das hochgeladene Paket zu entfernen.

OpenPay ist eine Marke ihres jeweiligen Inhabers. Diese Erweiterung ist nicht mit OpenPay verbunden und wird nicht von OpenPay unterstützt.