VibeFox OpenPay for WooCommerce — Hilfe
Anforderungen
WordPress: 6.0 oder neuer.
WooCommerce: 8.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.
PHP: 8.0 oder neuer.
HTTPS: Ihre Website muss HTTPS verwenden, da sich das Kartenformular auf Ihrer Kasse befindet.
OpenPay-Konto: 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 Dashboards für Sandbox und Produktion haben unterschiedliche Merchant-IDs und Schlüssel, und das Plugin hält sie getrennt.
VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert auf einer Domain.
Die Karte wird auf Ihrer Kasse eingegeben, aber im Browser von openpay.js gelesen und tokenisiert. Die Kartenfelder haben keinen Namen und werden nie an Ihren Server gesendet. Da sich das Kartenformular auf Ihrer Seite befindet, ist Ihr Geltungsbereich nach PCI DSS SAQ A-EP; fragen Sie Ihren Acquirer.
Installation
1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Alternativ können Sie den Ordner wcp_openpay_gateway per FTP nach /wp-content/plugins/ hochladen.
2. Klicken Sie auf Activate.
3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > OpenPay > Manage oder klicken Sie auf der Plugin-Seite unter dem Plugin-Namen auf Settings.
4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.
5. Wählen Sie das Account country und tragen Sie die Schlüssel für Sandbox und Produktion ein (siehe Konfiguration).
6. Empfohlen: Fügen Sie die Webhook-URL im OpenPay-Dashboard hinzu (siehe Konfiguration).
7. Aktivieren Sie Enable / Disable und speichern Sie. Testen Sie eine Zahlung mit den Testkarten der OpenPay-Sandbox und entfernen Sie danach das Häkchen bei Sandbox mode, um echte Zahlungen anzunehmen.
Konfiguration
Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > OpenPay. Oberhalb der Felder warnt die Seite, wenn die Schlüssel des aktuellen Modus unvollständig sind (die Zahlungsart wird dann an der Kasse ausgeblendet), wenn die Shop-Währung vom gewählten Kontoland nicht akzeptiert wird, und zeigt Sandbox mode is enabled — no real charges are made., solange der Sandbox-Modus aktiv ist. In der Liste der Zahlungsarten ist OpenPay als einrichtungsbedürftig markiert, bis der aktuelle Modus alle drei Schlüssel hat; solange der Sandbox-Modus aktiv ist, wird außerdem ein Testmodus-Abzeichen angezeigt.
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_. Ist die Zahlungsart aktiviert, aber die Schlüssel des aktuellen Modus sind unvollständig, sehen Sie außerdem einen Hinweis, dass das Gateway an der Kasse ausgeblendet bleibt.
Allgemein
Enable / Disable: Enable OpenPay card payments schaltet die Zahlungsart ein oder aus. Standard: aus.
Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: Credit or debit card (OpenPay).
Description: der Text über dem Kartenformular an der Kasse. Standard: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).
OpenPay-Konto
Merchant-ID, privater Schlüssel (sk_) und öffentlicher Schlüssel (pk_) finden Sie im OpenPay-Dashboard unter Settings (Configuración). Der Bereich enthält Links zu den Dashboards für Sandbox und Produktion für 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: Use the OpenPay sandbox (test keys, no real charges) schaltet sowohl die Schlüssel als auch die API auf die Sandbox um. Solange es aktiv ist, wird an der Kasse ein Abzeichen SANDBOX MODE angezeigt. Standard: an. Entfernen Sie das Häkchen, 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 nie weiter.
Sandbox Public Key: der öffentliche Sandbox-Schlüssel. Er beginnt mit pk_. openpay.js verwendet ihn im Browser zur Tokenisierung der Karte.
Live Merchant ID: die Merchant-ID aus dem Produktions-Dashboard, Settings (Configuración), API-Schlüssel.
Live Private Key: der private Produktionsschlüssel (sk_...).
Live Public Key: der öffentliche Produktionsschlüssel (pk_...).
Schlüssel aus Version 1.0 des Plugins (ein Schlüsselsatz und ein Sandbox-Schalter) werden automatisch in die Felder für Sandbox bzw. Produktion übernommen.
Webhook
Der Webhook ist nicht zwingend, wird aber empfohlen. Er bestätigt Zahlungen, wenn der Kunde nicht von der 3D-Secure-Seite zurückkehrt, zum Beispiel weil er den Browser geschlossen hat. Gehen Sie im OpenPay-Dashboard zu Settings > Webhooks und fügen Sie die URL hinzu, die in diesem Abschnitt der Einstellungen angezeigt wird. Sie sieht etwa so aus: https://your-site/wc-api/webhook_wc_openpay/. Kopieren Sie sie genau so, wie die Einstellungen sie anzeigen. Fügen Sie den Webhook im Dashboard jedes Modus hinzu, den Sie nutzen (Sandbox und Produktion).
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.
Wählen Sie diese Ereignisse aus:
OpenPay signiert Webhooks nicht, daher vertraut das Plugin der Benachrichtigung selbst nie. Es verwendet sie nur, um die Belastung zu finden, und liest die Belastung dann mit dem privaten Schlüssel des Modus, in dem die Bestellung bezahlt wurde, aus der OpenPay-API. Eine Benachrichtigung zu einer Belastung, die dieser Shop nicht erstellt hat, wird ignoriert.
Erweitert
Debug log: Log payment steps (errors are always logged) schreibt die Zahlungsschritte nach WooCommerce > Status > Logs, Quelle wcp_openpay_gateway. Fehler und Warnungen werden auch bei deaktiviertem Protokoll geschrieben. Schlüssel, Kartendaten und Kundendaten werden nie protokolliert. Standard: aus.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Standard: aus.
Kasse
Der Kunde wählt die Zahlungsart (standardmäßig Credit or debit card (OpenPay)) und füllt Cardholder name, Card number, Expiry (MM/YY) und Card code (CVV) aus. Beim Absenden der Bestellung wandelt openpay.js die Karte im Browser in ein Einmal-Token um, und die Betrugsprüfungsbibliothek von OpenPay fügt eine Geräte-Sitzungs-ID hinzu. Nur diese beiden Werte werden an Ihren Shop gesendet.
Das Plugin erstellt dann die Belastung mit 3D Secure für die Bestellsumme in der Bestellwährung und leitet den Kunden zur 3D-Secure-Seite seiner Bank weiter, die von OpenPay bereitgestellt wird. Jeder Versuch erhält eine eigene OpenPay-Bestellreferenz (die Bestellnummer und ein kurzes Suffix). Die Beschreibung der Belastung lautet Order #, die Bestellnummer und der Name Ihrer Website. Name, E-Mail und Telefonnummer des Kunden werden an OpenPay übergeben; es wird kein OpenPay-Kundenkonto angelegt. Die Bestellung bleibt auf Zahlung ausstehend, solange der Kunde auf der 3D-Secure-Seite ist.
Kehrt der Kunde zurück, liest das Plugin die Belastung aus der OpenPay-API. Die Bestellung wird erst als bezahlt markiert, wenn OpenPay sie bestätigt: Die Belastung muss zu dieser Bestellung gehören, abgeschlossen sein und Gesamtbetrag und Währung der Bestellung exakt entsprechen. Ist das Ergebnis noch nicht bekannt, zeigt die Seite „Bestellung eingegangen“ We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. an. Danach aktualisiert der Webhook die Bestellung.
Wird die Karte abgelehnt oder schlägt 3D Secure fehl, kehrt der Kunde auf die Seite Pay for order zurück, mit der Meldung The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card., und kann erneut bezahlen. Vor einem neuen Versuch prüft das Plugin die vorherige Belastung der Bestellung: War sie tatsächlich bezahlt, wird die Bestellung als bezahlt markiert, ohne eine zweite Belastung; ist sie noch in Bearbeitung, sieht der Kunde, dass eine frühere Zahlung noch verarbeitet wird, und sollte nicht erneut bezahlen; kann ihr Status nicht geprüft werden, wird kein neuer Versuch unternommen und der Kunde gebeten, es in einigen Minuten erneut zu versuchen.
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 die Bestellnotizen und das Protokoll.
Die Zahlungsart funktioniert in der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel. An der Kasse wird sie ausgeblendet, wenn sie deaktiviert ist, wenn die Schlüssel des aktuellen Modus unvollständig sind oder wenn die Bestellwährung vom Kontoland nicht akzeptiert wird.
Das Plugin nimmt nur Kartenzahlungen an, mit sofortiger Erfassung. Es unterstützt keine gespeicherten Karten, Abonnements, zinsfreien Monatsraten (MSI) oder Ratenzahlungen, keine Zahlung mit Kartenpunkten, Barzahlungen, SPEI, PSE oder CoDi und keine getrennte Autorisierung und Erfassung.
Bestellungen und Erstattungen
Bestellstatus
Zahlung ausstehend: der Kunde befindet sich auf der 3D-Secure-Seite oder hat die Zahlung noch nicht abgeschlossen. Eine Notiz zeigt die Belastungs-ID.
In Bearbeitung: die Zahlung wurde bestätigt. Dies ist der übliche WooCommerce-Status nach der Zahlung; Bestellungen mit nur virtuellen, herunterladbaren Produkten werden auf Abgeschlossen gesetzt. Die Bestellnotiz zeigt die Belastungs-ID und den Modus (Live oder Sandbox). Die Transaktions-ID ist die OpenPay-Belastungs-ID.
Wartend: die Belastung ist in Bearbeitung und noch nicht erfasst; oder OpenPay meldet eine abgeschlossene Belastung mit einem anderen Betrag oder einer anderen Währung als die Bestellung (die Bestellung wird nicht als bezahlt markiert, die Notiz zeigt die Abweichung); oder eine Zahlung ist für eine Bestellung eingegangen, die bereits storniert wurde. Prüfen Sie die Bestellung im OpenPay-Dashboard und erfüllen Sie sie oder erstatten Sie die Zahlung dort.
Fehlgeschlagen: die Karte wurde bei der Erstellung der Belastung abgelehnt, oder der letzte Versuch ist fehlgeschlagen, storniert worden oder abgelaufen. Der Kunde kann erneut bezahlen.
Geht für eine bereits bezahlte Bestellung eine zweite abgeschlossene Belastung ein, bleibt die Bestellung unverändert. Eine Notiz, die mit WARNING beginnt, fordert Sie auf, das Duplikat im OpenPay-Dashboard zu erstatten.
Erstattungen
Für Konten aus Mexiko und Peru: Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Credit or debit card (OpenPay) (die Schaltfläche zeigt den Titel Ihrer Zahlungsart). Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird im Modus und mit dem Kontoland gesendet, in denen die Bestellung bezahlt wurde; behalten Sie die Sandbox-Schlüssel also ausgefüllt, solange noch Sandbox-Bestellungen zu erstatten sind. Lehnt OpenPay die Erstattung ab, zeigt WooCommerce den Fehler an, zum Beispiel OpenPay refund failed: ..., und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird mit der OpenPay-Erstattungs-ID in die Bestellnotizen aufgenommen.
OpenPay Kolumbien unterstützt Kartenerstattungen über die API nicht, wie auch in den offiziellen OpenPay-Plugins. Für Kolumbien wird die Erstattungsschaltfläche nicht angeboten; erstatten Sie die Belastung im OpenPay-Dashboard.
Im OpenPay-Dashboard vorgenommene Erstattungen und Rückbuchungen kommen per Webhook an und werden einmal den Bestellnotizen hinzugefügt. Sie werden nicht automatisch als WooCommerce-Erstattungen erfasst. Erstellen Sie bei Bedarf eine manuelle Erstattung in WooCommerce ohne die OpenPay-Schaltfläche.
Lizenzschlüssel
Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > OpenPay. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain. Mit Check now prüfen Sie den Status erneut, mit Change key geben Sie einen anderen Schlüssel ein und mit Remove key entfernen Sie ihn von dieser Website. Der Link Manage licenses and domains in your account öffnet Ihr vibefox.net-Konto.
Ein Schlüssel funktioniert auf einer Domain. Das Entfernen des Schlüssels von einer Website gibt deren Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.
Ohne aktiven Schlüssel wird OpenPay Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsart weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Kauf eines Schlüssels einrichten und testen können. Ein Hinweis erscheint auf der Plugin-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.
Läuft eine Lizenz ab, funktioniert das Plugin weiter; Updates und Support erfordern jedoch eine Verlängerung. Der Status wird im Hintergrund automatisch erneut geprüft.
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 die Shop-Währung vom Account country akzeptiert wird (Mexiko: MXN, USD; Kolumbien: COP, USD; Peru: PEN, USD). Die Einstellungsseite zeigt in jedem Fall eine Warnung.
Die Zahlung ist durchgegangen, die Bestellung bleibt aber auf Zahlung ausstehend: 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 verwendeten Modus hinzugefügt ist, genau wie in den Einstellungen angezeigt, mit den oben aufgeführten Ereignissen. Prüfen Sie, ob die Schlüssel des Modus, in dem die Bestellung bezahlt wurde, eingetragen sind: Ohne sie antwortet der Webhook mit not configured, und OpenPay versucht es später erneut.
Der Webhook antwortet ignored (unknown order): die Belastung wurde nicht von diesem Shop für diese Bestellung erstellt, zum Beispiel eine Belastung eines anderen Shops auf demselben OpenPay-Konto. Es wird nichts geändert.
Der Webhook antwortet verification failed: die OpenPay-API war nicht erreichbar, um die Belastung abzurufen. OpenPay wiederholt den Webhook.
Der Webhook antwortet busy: die Bestellung wurde im selben Moment durch eine andere Anfrage aktualisiert. OpenPay wiederholt den Webhook.
Der Kunde sieht „The secure card form could not be loaded“: openpay.js oder die Betrugsprüfungsbibliothek von OpenPay wurden 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 in den Bestellnotizen und im Protokoll, Quelle wcp_openpay_gateway. Eine typische Ursache ist eine falsche Merchant-ID oder ein falscher privater Schlüssel. Hat OpenPay nicht geantwortet, prüfen Sie die Belastung im OpenPay-Dashboard, bevor der Kunde erneut bezahlt.
„This test card cannot be used for real payments“: es wurde eine Sandbox-Testkarte verwendet, während der Sandbox-Modus deaktiviert ist.
Bestellung nach der Zahlung auf Wartend: lesen Sie die Bestellnotiz. Die Belastung ist noch in Bearbeitung, der gezahlte Betrag oder die Währung weicht von der Bestellung ab, oder die Zahlung kam, nachdem die Bestellung storniert wurde.
Erstattung schlägt mit einer Meldung zum Modus fehl: die Bestellung wurde im Sandbox- oder Live-Modus bezahlt, und die Schlüssel dieses Modus sind nicht hinterlegt. Tragen Sie sie ein und versuchen Sie es erneut.
Der Lizenzblock zeigt einen Fehler: folgen Sie der Meldung im Block. Wenn der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet wird, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Hat sich die Adresse der Website geändert, klicken Sie auf Check now, um den Schlüssel für die neue Domain zu aktivieren. Ist der Lizenzserver nicht erreichbar, arbeitet das Plugin mit dem zuletzt bekannten Status weiter.
Deinstallation
Das Deaktivieren des Plugins behält alle Daten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Lizenzschlüssel und Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen, der gespeicherte Verifizierungscode des Webhooks und die Protokolle des Plugins werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestelldaten bleiben immer erhalten: Bestehende Bestellungen behalten ihre Zahlungsnotizen, Transaktions-IDs und die für Erstattungen nach einer Neuinstallation benötigten Belastungsdaten.
OpenPay ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit OpenPay verbunden noch wird es von OpenPay unterstützt.