VibeFox Omise for WooCommerce — Hilfe

Anforderungen

WordPress: 6.2 oder neuer.

WooCommerce: 8.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren; wird WooCommerce später deaktiviert, wird das Gateway nicht geladen und ein Admin-Hinweis angezeigt.

PHP: 8.0 oder neuer.

HTTPS: Die Kartenfelder befinden sich auf Ihrer Kasse, daher muss die Kasse über HTTPS ausgeliefert werden und frei von nicht vertrauenswürdigen Skripten sein. Kartendaten erreichen Ihren Server trotzdem nie. Omise sendet Webhooks nur an HTTPS-Adressen.

Shop-Währung: eine der Währungen THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Bei anderen Währungen wird die Zahlungsart an der Kasse ausgeblendet.

Omise-Konto: Sie benötigen den öffentlichen und den geheimen Schlüssel Ihres Omise-Kontos für den Test- und den Live-Modus, zu finden unter Settings > Keys im Omise-Dashboard, sowie einen Webhook-Endpunkt unter Settings > Webhooks (siehe Konfiguration).

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert auf einer Domain.

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_omise_payment per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Omise > 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. Tragen Sie Ihre Omise-Test- und Live-Schlüssel ein und hinterlegen Sie die auf der Einstellungsseite angezeigte Webhook-URL im Omise-Dashboard (siehe Konfiguration).

6. Aktivieren Sie Enable/Disable. Testen Sie eine Zahlung im Testmodus mit einer Omise-Testkarte wie 4242 4242 4242 4242 und entfernen Sie danach das Häkchen bei Test mode.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Omise. Oberhalb der Felder zeigt die Seite Test mode is on — orders are charged with the test keys, no real money is moved. an, solange der Testmodus aktiv ist, und warnt, wenn der öffentliche oder der geheime Schlüssel des aktuellen Modus fehlt oder die Shop-Währung von Omise nicht unterstützt wird. In beiden Fällen wird die Zahlungsart an der Kasse ausgeblendet. In der Liste der Zahlungsarten ist Omise als einrichtungsbedürftig markiert, bis beide Schlüssel des aktuellen Modus eingetragen sind.

Allgemein

Enable/Disable: Enable card payments via Omise schaltet die Zahlungsart ein oder aus. Standard: aus.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: Credit / Debit Card.

Description: der Text über dem Kartenformular an der Kasse. Standard: Pay securely with your credit or debit card via Omise.

API-Schlüssel

Ihre Schlüssel finden Sie im Omise-Dashboard unter Settings > Keys. Testschlüssel beginnen mit pkey_test_ und skey_test_, Live-Schlüssel mit pkey_ und skey_. Beim Speichern wird ein Schlüssel mit falschem Präfix (zum Beispiel ein Testschlüssel in einem Live-Feld) mit einer Fehlermeldung abgelehnt, und der bisherige Wert bleibt erhalten.

Test mode: Use the test keys (no real charges). Schaltet beide Schlüssel um. Erstattungen, Erfassungen und Statusprüfungen einer Bestellung verwenden immer die Schlüssel des Modus, in dem die Bestellung bezahlt wurde. Standard: an.

Test public key: der öffentliche Schlüssel des Testmodus, pkey_test_...

Test secret key: der geheime Schlüssel des Testmodus, skey_test_...

Live public key: der öffentliche Schlüssel des Live-Modus, pkey_...

Live secret key: der geheime Schlüssel des Live-Modus, skey_...

Zahlung und Webhook

Der Bereich zeigt die Webhook-URL Ihres Shops. Sie sieht etwa so aus: https://your-site/wp-json/omise-payment/v1/webhook. Kopieren Sie sie genau so, wie die Einstellungen sie anzeigen, und tragen Sie sie im Omise-Dashboard unter Settings > Webhooks ein (nur HTTPS). Das Plugin verarbeitet diese Ereignisse:

Dem Inhalt des Webhooks wird nie vertraut: Die Belastung muss die in der Bestellung gespeicherte sein, und ihr Status wird mit den Schlüsseln des Modus der Bestellung erneut über die Omise-API abgerufen. Ohne Webhook bleibt eine Bestellung, deren Kunde während 3-D Secure den Browser schließt, auf Wartend, bis Sie Omise: Sync payment status ausführen, und im Omise-Dashboard vorgenommene Erfassungen werden nicht automatisch übernommen.

Payment action: was mit dem Kartenbetrag geschieht.

Per-charge webhook: Send the webhook URL with every charge. Nützlich, wenn mehrere Shops ein Omise-Konto teilen. Funktioniert nur, wenn die Website HTTPS nutzt; andernfalls wird der Webhook aus dem Dashboard verwendet. Standard: aus.

Erweitert

Debug log: Log API requests and payment events schreibt Zahlungsereignisse nach WooCommerce > Status > Logs, Quelle wcp_omise_payment. Schlüssel, Token und Kartendaten werden nie protokolliert. Standard: aus.

Delete data on uninstall: Remove the settings and debug logs when the plugin is deleted. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Credit / Debit Card) und füllt das Kartenformular aus: Name on card, Card number, Expiry month (MM), Expiry year (YYYY) und Security code (CVV). Im Testmodus zeigt das Formular TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. an. Beim Absenden der Bestellung wandelt Omise.js die Karte im Browser in ein Einmal-Token um. Die Kartenfelder werden nie an Ihren Server übermittelt.

Ihr Shop erstellt die Belastung mit dem geheimen Schlüssel über die Bestellsumme in der Bestellwährung. Die Beschreibung der Belastung ist der Shop-Name und die Bestellnummer; die Bestell-ID wird in den Metadaten der Belastung gespeichert. Verlangt die Bank 3-D Secure, wird der Kunde zur Bank und danach zurück in Ihren Shop geleitet. Das Ergebnis wird immer erneut über die Omise-API abgerufen.

Die Bestellung wird erst als bezahlt markiert, wenn Omise es bestätigt: Die Belastung muss erfasst sein, und Betrag und Währung müssen mit der Bestellung übereinstimmen. Bei Authorize only wird die Bestellung nach erfolgreicher Autorisierung auf Wartend gesetzt. Der Kunde sieht die Bestellbestätigungsseite.

Wird die Karte abgelehnt, bleibt der Kunde an der Kasse mit Payment failed: und einem Grund, zum Beispiel unzureichende Deckung, ein ungültiger Sicherheitscode oder eine Ablehnung durch den Kartenaussteller, und kann es erneut versuchen. Nach einem fehlgeschlagenen 3-D Secure gelangt der Kunde zur Seite Pay for order. Kann die Zahlung direkt nach 3-D Secure nicht bestätigt werden, sieht der Kunde We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again.

Ein Wiederholungsversuch belastet nie doppelt: Ist die vorherige Belastung der Bestellung bereits bezahlt oder autorisiert, wird die Bestellung ohne neue Belastung abgeschlossen. Ein nicht abgeschlossener 3-D-Secure-Versuch läuft ab, bevor eine neue Belastung erstellt wird.

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.

Das Plugin akzeptiert nur Karten. Es gibt keine weiteren Omise-Zahlungsarten (PromptPay, TrueMoney, Mobile Banking, Ratenzahlung, Konbini, PayNow), keine gespeicherten Karten oder Omise-Kunden, keine Abonnements und keine Teilerfassung.

Bestellungen und Erstattungen

Bestellstatus

Zahlung ausstehend: der Kunde befindet sich bei 3-D Secure oder hat noch nicht bezahlt.

In Bearbeitung: die Zahlung wurde bestätigt. Bestellungen mit nur virtuellen, herunterladbaren Produkten werden wie üblich in WooCommerce auf Abgeschlossen gesetzt. Die Bestellnotiz zeigt den Betrag, die Belastungs-ID und die Art der Bestätigung (Kasse, Rückkehr von 3-D Secure, Webhook, manuelle Erfassung oder manuelle Synchronisierung). Die Transaktions-ID ist die Omise-Belastungs-ID (chrg_...).

Wartend, Erfassung ausstehend: die Karte wurde mit Authorize only autorisiert. Verwenden Sie Omise: Capture payment oder Omise: Void authorization.

Wartend, Zahlung ausstehend: Omise hat die Zahlung noch nicht bestätigt, zum Beispiel weil der Kunde während 3-D Secure den Browser geschlossen hat. Der Webhook oder Omise: Sync payment status aktualisiert die Bestellung.

Wartend, Abweichung: der Betrag oder die Währung der Belastung weicht von der Bestellung ab. Die Notiz zeigt beide Werte. Prüfen Sie die Bestellung und schließen Sie sie ab oder erstatten Sie die Zahlung.

Fehlgeschlagen: die Zahlung wurde abgelehnt. Eine bezahlte Bestellung wird durch ein späteres Fehler-Ereignis nie zurückgestuft.

Storniert: die Belastung ist abgelaufen oder die Autorisierung wurde storniert.

Trifft eine bezahlte oder autorisierte Belastung für eine bereits stornierte oder erstattete Bestellung ein, wird die Bestellung nicht wieder geöffnet. Eine Notiz fordert Sie auf, das Omise-Dashboard zu prüfen und die Zahlung manuell zu erstatten oder die Bestellung wieder zu öffnen.

Bestellaktionen

Omise: Capture payment: erfasst den vollen autorisierten Betrag. Wird nur bei autorisierten Bestellungen angezeigt.

Omise: Void authorization: storniert die Autorisierung; es wird kein Geld erfasst und die Bestellung wird storniert. Wird nur bei autorisierten Bestellungen angezeigt.

Omise: Sync payment status: liest die Belastung bei Omise aus und aktualisiert die Bestellung. Die Notiz zeigt außerdem die bei Omise insgesamt erstattete Summe.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Omise. Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird in dem Modus gesendet, in dem die Zahlung erfolgte; daher muss der geheime Schlüssel dieses Modus hinterlegt sein. Eine erfolgreiche Erstattung wird mit der Omise-Erstattungs-ID in die Bestellnotizen aufgenommen. Bei einer noch nicht erfassten Autorisierung ist nur eine vollständige Erstattung möglich, und sie storniert die Autorisierung. Lehnt Omise die Erstattung ab, zeigt WooCommerce Refund failed. mit der Meldung von Omise an, und es wird keine Erstattung erfasst.

Im Omise-Dashboard vorgenommene Erstattungen werden nicht als WooCommerce-Erstattungen übernommen. Omise: Sync payment status zeigt die erstattete Gesamtsumme; legen Sie bei Bedarf passende manuelle Erstattungen in WooCommerce an.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Omise. 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 Omise 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 Erfassungen 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

Omise erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, beide Schlüssel des aktuellen Modus eingetragen sind (Testschlüssel im Testmodus, sonst Live-Schlüssel) und die Währung unterstützt wird. Auf der Seite Pay for order zählt die Bestellwährung. Die Einstellungsseite zeigt eine Warnung, wenn Schlüssel oder Währung nicht passen.

Die Zahlung ist durchgegangen, die Bestellung bleibt aber auf Zahlung ausstehend oder Wartend: der Webhook funktioniert nicht. Prüfen Sie im Omise-Dashboard, ob die Webhook-URL genau der Adresse aus den Einstellungen entspricht und HTTPS verwendet. Führen Sie danach Omise: Sync payment status für die Bestellung aus. Aktivieren Sie das Debug log, um die Webhook-Antworten zu sehen.

Der Webhook meldet Earlier charge of the order, order not changed: das Ereignis betrifft einen früheren Versuch der Bestellung, der durch einen Wiederholungsversuch ersetzt wurde. An der Bestellung wird nichts geändert. Ist diese frühere Belastung bei Omise noch bezahlt oder autorisiert, weist eine Bestellnotiz einmalig darauf hin: Prüfen Sie das Omise-Dashboard auf eine Doppelzahlung und erstatten oder stornieren Sie sie dort.

Der Webhook meldet Charge ID does not match order: die Belastung im Ereignis gehört zu einer anderen Bestellung. Es wird nichts geändert.

Der Webhook meldet Order is being processed, retry later oder Failed to verify charge: die Bestellung war durch eine andere Anfrage gesperrt, oder die Omise-API war nicht erreichbar. Omise wiederholt den Webhook.

Fehler beim Speichern: key must start with ... oder must be a live key: ein Schlüssel wurde in das falsche Feld eingefügt. Testschlüssel beginnen mit pkey_test_ / skey_test_, Live-Schlüssel mit pkey_ / skey_.

Der Kunde sieht Card payments are temporarily unavailable: die Schlüssel sind falsch, oder das Karten-Token gehört zum anderen Modus (ein Test-Token im Live-Modus oder umgekehrt). Prüfen Sie die Schlüssel und Test mode.

Der Kunde sieht We could not reach the payment provider: Omise hat beim Erstellen der Belastung keine gültige Antwort gesendet. Eine Belastung kann dennoch angelegt worden sein; die Bestellnotiz fordert Sie auf, das Omise-Dashboard zu prüfen, bevor Sie die Bestellung erneut belasten.

Der Kunde sieht This order is already being paid: die Kasse wurde zweimal gleichzeitig übermittelt. Der Kunde wartet und prüft seine E-Mail, bevor er es erneut versucht.

Bestellung nach der Zahlung auf Wartend: lesen Sie die Bestellnotiz. Die Bestellung wartet auf die Erfassung, Omise hat die Zahlung noch nicht bestätigt, oder Betrag oder Währung weichen von der Bestellung ab.

Erstattung schlägt mit einer Meldung zum Modus fehl: die Zahlung erfolgte im Test- oder Live-Modus, und der geheime Schlüssel dieses Modus ist nicht hinterlegt. Tragen Sie ihn ein und versuchen Sie es erneut.

Teilerstattung einer autorisierten Bestellung schlägt fehl: die Zahlung ist nur autorisiert. Erfassen Sie sie zuerst, oder erstatten Sie den vollen Betrag, um sie zu stornieren.

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 und die Protokolle werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Omise-Daten, die in Bestellungen gespeichert sind, gehören zur Zahlungshistorie und bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Omise ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Omise verbunden noch wird es von Omise unterstützt.