VibeFox KOMOJU for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer.

HTTPS: Ihre Website benötigt HTTPS, und KOMOJU muss die Webhook-URL erreichen können.

KOMOJU account: Sie benötigen den geheimen Schlüssel (sk_live_... und für den Testmodus sk_test_...) und das geheime Token eines im KOMOJU-Dashboard erstellten Webhooks (siehe Konfiguration). Der veröffentlichbare Schlüssel wird nicht benötigt.

Store currency: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD oder VND. Bei anderen Währungen wird die Zahlungsmethode ausgeblendet.

VibeFox license key: auf vibefox.net gekauft. Ein Schlüssel funktioniert auf einer Domain.

Installation

1. Öffnen Sie in WordPress Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Sie können den Ordner wcp_komoju_payment auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > KOMOJU Payment > Manage, oder klicken Sie unter dem Plugin-Namen auf der Plugins-Seite auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

5. Fügen Sie im KOMOJU-Dashboard einen Webhook mit der URL und den Ereignissen der Einstellungsseite hinzu und kopieren Sie sein geheimes Token (siehe Konfiguration).

6. Geben Sie den geheimen Live-Schlüssel und das geheime Live-Webhook-Token sowie die Testwerte für den Sandbox-Modus ein. Aktivieren Sie Enable/Disable und speichern Sie.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > KOMOJU Payment. über den Feldern erscheint bei aktivem Testmodus KOMOJU Sandbox Mode is enabled.. Die Seite warnt, wenn im aktuellen Modus der geheime Schlüssel fehlt (die Zahlungsmethode wird dann an der Kasse ausgeblendet) oder das geheime Webhook-Token fehlt (KOMOJU-Benachrichtigungen werden dann abgewiesen, sodass Konbini- und Überweisungszahlungen nie bestätigt werden), sowie bei nicht unterstützter Shopwährung. In der Zahlungsmethodenliste gilt KOMOJU als noch einzurichten, bis der aktuelle Modus einen geheimen Schlüssel hat; im Sandbox-Modus erscheint ein Testmodus-Abzeichen.

Allgemein

Enable/Disable: Enable KOMOJU Payment Gateway schaltet die Zahlungsmethode ein oder aus. Standard: off.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: KOMOJU Payment.

Description: der Text unter der Zahlungsmethode an der Kasse. Standard: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.

Live-API-Schlüssel

Die Schlüssel finden Sie im KOMOJU-Dashboard: den geheimen Schlüssel unter Settings > API keys, das geheime Webhook-Token unter Settings > Webhooks (fügen Sie dort zuerst die unten angezeigte Webhook-URL hinzu).

Live Secret Key: Ihr geheimer KOMOJU-Live-Schlüssel. Er beginnt mit sk_live_.

Live Webhook Secret Token: das geheime Token des Live-Webhooks. Damit wird die Signatur jeder Benachrichtigung geprüft.

Testmodus

KOMOJU nutzt für Test- und Live-Zahlungen dieselbe API-Adresse: Der Schlüssel entscheidet. Bestellungen behalten ihren Zahlungsmodus, sodass Erstattungen und Statusprüfungen stets den Schlüssel dieses Modus verwenden.

Sandbox Mode: Enable test mode (use the test keys below, no real payments). Standard: off. Bei Aktivierung zeigt die Kasse über der Beschreibung Test mode.

Sandbox Secret Key: Ihr geheimer KOMOJU-Testschlüssel. Er beginnt mit sk_test_.

Sandbox Webhook Secret Token: das geheime Token des Testmodus-Webhooks.

Webhook-URL

Der Webhook informiert Ihren Shop über Zahlungen, auch verzögerte Konbini- und Überweisungszahlungen. Fügen Sie im KOMOJU-Dashboard unter Settings > Webhooks die URL aus diesem Einstellungsabschnitt für Live- und Testmodus hinzu. Sie sieht so aus: https://your-site/wc-api/komoju_p_webhook/. Falls Ihre Website Sprachpräfixe in URLs verwendet, kopieren Sie die URL exakt wie angezeigt. Kopieren Sie anschließend das geheime Token jedes Webhooks in Live Webhook Secret Token oder Sandbox Webhook Secret Token.

Wählen Sie diese Ereignisse:

payment.authorized: der Zahlungsbeleg wurde ausgestellt (konbini, Banküberweisung) oder die Zahlung autorisiert. Die Bestellung kommt bis zur Zahlung in Wartestellung.

payment.captured: die Zahlung wurde abgeschlossen. Nach der Betrags- und Währungsprüfung wird die Bestellung als bezahlt markiert.

payment.expired: der Zahlungsbeleg ist abgelaufen. Die Bestellung wird storniert.

payment.cancelled: die Zahlung wurde storniert. Die Bestellung wird storniert.

payment.failed: die Zahlung ist fehlgeschlagen. Die Bestellung erhält den Status Fehlgeschlagen; der Kunde kann es erneut versuchen.

payment.refund.created: eine Erstattung wurde vorgenommen, etwa im KOMOJU-Dashboard. Sie wird in WooCommerce erfasst.

payment.refunded: die Zahlung wurde erstattet. Die Erstattung wird in WooCommerce erfasst.

Ablauf-, Stornierungs- und Fehlerereignisse ändern die Bestellung nur für ihre aktuelle Zahlung. So kann die Zahlung eines früheren Versuchs keine Bestellung stornieren, die gerade anders bezahlt wird. Webhooks ohne gültige Signatur werden abgewiesen. Mit einem der beiden geheimen Token signierte Webhooks werden akzeptiert, jedoch nur für Bestellungen desselben Modus. Ohne Webhook werden Kartenzahlungen bei der Rückkehr des Kunden bestätigt, Konbini- und Überweisungszahlungen jedoch nie.

Erweitert

Invoice Prefix: das Präfix der an KOMOJU gesendeten Bestellnummern. Bei mehreren Shops mit demselben KOMOJU-Konto muss es für jeden Shop eindeutig sein. Standard: WC-.

Enable Logging: Log KOMOJU events and API calls unter WooCommerce > Status > Logs, Quelle wcp_komoju_payment, ohne Schlüssel oder Kundendaten. Fehler werden immer protokolliert. Standard: off.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Das Deaktivieren des Plugins löscht nie etwas. Bestelldaten (KOMOJU-Zahlungs-IDs in Bestellungen) bleiben immer erhalten. Standard: off.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig KOMOJU Payment) und bestellt. Das Plugin erstellt eine KOMOJU-Zahlungssitzung über den Bestellgesamtbetrag in der Bestellwährung und leitet den Kunden zur KOMOJU-Zahlungsseite weiter. Rechnungs-E-Mail, Name, Rechnungs- und Lieferadressen sowie bestellte Artikel werden an KOMOJU übergeben. Die Seite erscheint je nach Websitesprache auf Japanisch, Englisch oder Koreanisch (bei anderen Sprachen auf Englisch). Dort wählt der Kunde eine Zahlungsmethode. Die angebotenen Methoden hängen von Ihrem KOMOJU-Konto und der Bestellwährung ab.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Das Plugin ruft die Zahlungssitzung über die KOMOJU-API mit dem Schlüssel des Bestellmodus ab. Die Bestellung wird erst als bezahlt markiert, wenn KOMOJU bestätigt: durch den signierten Webhook oder den Sitzungsabruf bei der Rückkehr. Ist KOMOJU dann nicht erreichbar, gelangt der Kunde auf die Bestelleingangsseite mit We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes.

Bei Konbini- und Überweisungszahlungen erhält der Kunde einen Zahlungsbeleg. Die Bestellung kommt in Wartestellung und wird abgeschlossen, wenn der Kunde bezahlt und KOMOJU den Webhook sendet. Läuft der Beleg ab, wird sie storniert.

Wurde die Zahlung nicht abgeschlossen, kehrt der Kunde auf die Seite Pay for order zurück, mit The payment was not completed. You can try again or choose another payment method. Ein neuer Versuch verwendet die offene KOMOJU-Sitzung, sofern der Gesamtbetrag unverändert ist. Eine Sitzung mit altem Gesamtbetrag wird in KOMOJU storniert; eine inzwischen bezahlte Sitzung bestätigt die Bestellung. Wird eine unbezahlte Bestellung storniert (durch Sie, den Kunden oder den WooCommerce-Timer für reservierten Lagerbestand), wird auch ihre offene KOMOJU-Sitzung storniert, sodass sie nicht mehr bezahlt werden kann.

Kann KOMOJU die Zahlung nicht starten, sieht der Kunde eine kurze Nachricht, etwa KOMOJU could not accept this payment: mit dem Grund, KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. oder Payment error: Could not connect to KOMOJU. Please try again in a moment. Details werden den Bestellnotizen und dem Protokoll hinzugefügt.

Die Zahlungsmethode 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 bietet kein Kartenformular auf Ihrer Website, keine gespeicherten Karten oder Abonnements. Es beschränkt die Zahlungsmethoden nicht: Diese werden auf der KOMOJU-Seite gewählt. Es gibt keine manuelle Erfassung: Dafür autorisierte Zahlungen müssen im KOMOJU-Dashboard erfasst werden; bis dahin bleibt die Bestellung in Wartestellung.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: der Kunde wurde zu KOMOJU geleitet und hat noch nicht bezahlt, oder KOMOJU hat die Zahlung noch nicht bestätigt.

Processing or Completed: KOMOJU hat die Zahlung bestätigt. WooCommerce setzt den üblichen Status einer bezahlten Bestellung. Die Bestellnotiz enthält KOMOJU-Zahlungs-ID, Zahlungsmethode und Bestätigungsart (Webhook oder Rückkehr). Die Transaktions-ID entspricht der KOMOJU-Zahlungs-ID und verlinkt auf der Bestellseite zur Zahlung im KOMOJU-Dashboard.

On hold: ein Konbini- oder Überweisungsbeleg wurde ausgestellt und wartet auf Zahlung, oder eine Zahlung wartet auf Erfassung im KOMOJU-Dashboard. Eine Bestellung kommt auch in Wartestellung, wenn Betrag oder Währung nicht übereinstimmen oder eine Zahlung nach der Stornierung erfasst wurde. Die Bestellnotiz erläutert dies. Führen Sie die Bestellung aus oder erstatten Sie die Zahlung.

Failed: die Zahlung ist fehlgeschlagen. Der Kunde kann es erneut versuchen.

Cancelled: der Zahlungsbeleg ist abgelaufen oder die Zahlung wurde storniert.

Refunded: die Zahlung wurde vollständig erstattet, über WooCommerce oder im KOMOJU-Dashboard.

Wird eine zweite Zahlung für eine bereits bezahlte Bestellung erfasst, wird die Bestellung nicht erneut geändert. Eine Notiz fordert Sie auf, eine doppelte Zahlung im KOMOJU-Dashboard zu erstatten. Erstattete Bestellungen werden nie wieder geöffnet.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via KOMOJU Payment. Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung verwendet den Schlüssel des ursprünglichen Zahlungsmodus; dessen geheimer Schlüssel muss daher hinterlegt sein. Das Plugin prüft zuerst die Zahlung in KOMOJU und verweigert Erstattungen über dem noch erstattbaren Betrag. Kann KOMOJU eine Zahlung nicht automatisch erstatten (einige Methoden wie konbini benötigen die Bankdaten des Kunden), erscheint die KOMOJU-Fehlermeldung und es wird nichts erfasst: Bearbeiten Sie solche Erstattungen im KOMOJU-Dashboard. Eine Erstattung gilt erst nach Bestätigung durch KOMOJU als erfolgt. Erfolgreiche Erstattungen werden den Bestellnotizen hinzugefügt.

Bei Zahlungen, die KOMOJU in eine andere Währung umgerechnet hat (etwa konbini in JPY für eine EUR-Bestellung), sind über WooCommerce nur vollständige Erstattungen möglich. Nehmen Sie Teilerstattungen im KOMOJU-Dashboard vor.

Erstattungen im KOMOJU-Dashboard treffen per Webhook ein und werden automatisch als WooCommerce-Erstattungen erfasst. Eine vollständige Erstattung setzt den Status auf Rückerstattet. Teilerstattungen im Dashboard für umgerechnete Zahlungen werden nur in der Bestellung vermerkt: Erfassen Sie den entsprechenden Betrag in WooCommerce mit "Refund manually".

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock steht oben auf WooCommerce > Settings > Payments > KOMOJU Payment. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status, etwa das Ablaufdatum der Lizenz und Ihre Domain. Mit Check now prüfen Sie 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 von einer Website gibt den Domainplatz nicht frei. Geben Sie ihn in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel sehen Kunden KOMOJU an der Kasse nicht. Wird dennoch eine Zahlung gestartet, erscheint This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Methode weiterhin mit (unlicensed — visible to admins only), damit Sie das Plugin vor dem Schlüsselkauf einrichten und testen können. Auf der Plugins-Seite und WooCommerce-Seiten erscheint eine Erinnerung. Bestehende Bestellungen sind nicht betroffen: Gestartete Zahlungen werden weiter bestätigt und Erstattungen funktionieren.

Nach Ablauf der Lizenz funktioniert das Plugin weiter; Updates und Support erfordern eine Verlängerung. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

KOMOJU erscheint nicht an der Kasse: Prüfen Sie die aktive Lizenz, die Aktivierung von Enable/Disable und den geheimen Schlüssel des aktuellen Modus: Sandbox Secret Key im Sandbox-Modus, Live Secret Key im Live-Modus. KOMOJU muss die Shopwährung unterstützen. Die Einstellungsseite warnt bei fehlenden Angaben.

Die Zahlung war erfolgreich, aber die Bestellung bleibt Pending payment: Der Webhook funktioniert nicht. Prüfen Sie im KOMOJU-Dashboard, ob er für den verwendeten Modus existiert, seine URL exakt den Einstellungen entspricht und die Ereignisse ausgewählt sind. Prüfen Sie sein geheimes Token im passenden Feld (Live Webhook Secret Token oder Sandbox Webhook Secret Token) und sehen Sie unter WooCommerce > Status > Logs, Quelle wcp_komoju_payment, nach. Kartenzahlungen werden auch bei der Rückkehr des Kunden bestätigt, Konbini- und Überweisungszahlungen nur per Webhook.

Webhook antwortet Failed to verify KOMOJU webhook signature: Das geheime Token fehlt oder gehört zu einem anderen Webhook. KOMOJU wiederholt die Benachrichtigung.

Webhook antwortet Mode mismatch, ignored: Der Webhook wurde mit dem Token des anderen Modus signiert als dem Zahlungsmodus der Bestellung. Verwenden Sie getrennte Webhooks und Token für Live- und Testmodus.

Webhook antwortet Order is busy, retry later oder Temporary error, retry later: Die Bestellung wurde durch eine andere Anfrage aktualisiert, oder die Zahlung konnte gerade nicht geprüft werden. KOMOJU wiederholt die Benachrichtigung.

Bestellung ist On hold: Lesen Sie die Bestellnotiz. Ein Beleg wartet auf Zahlung, eine Zahlung auf Erfassung im KOMOJU-Dashboard, Betrag oder Währung stimmten nicht überein, oder die Zahlung kam nach der Stornierung.

Erstattung schlägt fehl: Lesen Sie die Nachricht. Eventuell fehlt der geheime Schlüssel des Zahlungsmodus, die Zahlung kann nicht automatisch erstattet werden (nutzen Sie das KOMOJU-Dashboard), oder bei umgerechneten Zahlungen ist nur eine vollständige Erstattung möglich.

Der Lizenzblock zeigt einen Fehler: Folgen Sie der Meldung. Wird der Schlüssel bereits auf einer anderen Domain verwendet, geben Sie einen Platz im vibefox.net-Konto frei und klicken Sie auf Check now. Hat sich die Websiteadresse 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.

Entwickler können die Währungsliste mit dem Filter komoju_p_supported_currencies und die Zahlungssitzung, etwa Zahlungsmethoden, mit dem Filter komoju_p_session_params ändern.

Deinstallation

Das Deaktivieren erhält alle Daten. Zum Entfernen deaktivieren und löschen Sie das Plugin auf der Seite Plugins. Lizenzschlüssel und Lizenzstatus dieses Plugins werden immer entfernt. Gateway-Einstellungen und Protokolle werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten Zahlungsnotizen und Transaktions-IDs.

KOMOJU ist eine Marke des jeweiligen Eigentümers. Dieses Plugin ist weder mit KOMOJU verbunden noch von KOMOJU unterstützt.