VibeFox Moyasar for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 8.0 oder neuer, installiert und aktiv. Bei einer älteren WooCommerce-Version zeigt das Plugin einen Hinweis an und wird nicht geladen.

PHP: 8.0 oder neuer.

Währung: Die Shop- oder Bestellwährung muss SAR, AED, USD, EUR, KWD, BHD oder OMR sein. Bei allen anderen Währungen wird die Zahlungsart an der Kasse ausgeblendet.

Moyasar-Konto: Sie benötigen die geheimen API-Schlüssel Ihres Moyasar-Kontos (Test und Live). Nur die geheimen Schlüssel werden verwendet. Der öffentliche Schlüssel (Publishable Key) wird nicht benötigt, da die Zahlung auf der Moyasar-Seite erfolgt. Ein Webhook im Moyasar Dashboard wird empfohlen (siehe Konfiguration).

VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. 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. Sie können auch den Ordner wcp_moyasar_payment_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

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

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

5. Fügen Sie Ihre geheimen Moyasar-Schlüssel ein und speichern Sie. Richten Sie den Webhook im Moyasar Dashboard mit der URL und dem gemeinsamen Geheimnis ein, die in den Einstellungen angezeigt werden (siehe Konfiguration).

6. Aktivieren Sie Enable/Disable. Legen Sie eine Testbestellung im Testmodus an und entfernen Sie danach den Haken bei Test mode.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Moyasar. Der Seitentitel zeigt eine Kennzeichnung TEST MODE oder LIVE. Oberhalb der Felder warnt die Seite, wenn für den aktuellen Modus kein geheimer Schlüssel hinterlegt ist (die Zahlungsart wird dann an der Kasse ausgeblendet) oder die Shop-Währung nicht unterstützt wird. Solange der Testmodus aktiv ist, zeigt sie Test mode is active: payments are simulated, no money is charged. an. In der Liste der Zahlungsarten ist Moyasar als einrichtungsbedürftig markiert, bis für den aktuellen Modus ein geheimer Schlüssel vorhanden ist. Beim Speichern lehnt das Plugin einen öffentlichen Schlüssel, einen Schlüssel des anderen Modus oder einen Schlüssel mit Leerzeichen ab, behält den bisherigen Wert bei und nennt den Grund. Außerdem warnt es, wenn das Gateway aktiviert ist, der geheime Schlüssel des aktuellen Modus aber leer ist.

Allgemein

Enable/Disable: Enable Moyasar aktiviert oder deaktiviert die Zahlungsart. Standard: aus.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Standard: Pay with Moyasar.

Description: der Text unter der Zahlungsart an der Kasse. Standard: You will be redirected to the secure Moyasar payment page to pay with mada, Visa, Mastercard, Apple Pay or STC Pay. Im Testmodus ergänzt die Kasse (Test mode: no real payment is made.).

API-Schlüssel

Kopieren Sie die geheimen Schlüssel aus Moyasar Dashboard > Settings > API Keys. Test- und Live-Schlüssel sind getrennt. Der Testmodus verwendet nur den Testschlüssel, der Live-Modus nur den Live-Schlüssel.

Test mode: Enable test mode verwendet den geheimen Testschlüssel: Zahlungen werden simuliert und es wird kein Geld abgebucht. Standard: ein. Schalten Sie es aus, um echte Zahlungen mit dem geheimen Live-Schlüssel anzunehmen.

Test secret key: der geheime Schlüssel des Testmodus. Er beginnt mit sk_test_.

Live secret key: der geheime Schlüssel des Live-Modus. Er beginnt mit sk_live_.

Zahlungsbenachrichtigungen (Webhook)

Der Webhook wird empfohlen, ist aber nicht erforderlich. Bestellungen werden auch bestätigt, wenn der Kunde in den Shop zurückkehrt, und durch die Rechnungsbenachrichtigung, die Moyasar automatisch an Ihren Shop sendet, sobald die Rechnung bezahlt ist. Der Webhook deckt Kunden ab, die den Browser schließen, bevor sie zurückkehren, und informiert über Erstattungen, die im Moyasar Dashboard vorgenommen wurden. Fügen Sie im Moyasar Dashboard > Settings > Webhooks einen Webhook mit der URL und dem gemeinsamen Geheimnis aus diesem Abschnitt hinzu, HTTP-Methode POST.

Webhook URL: wird schreibgeschützt mit einer Schaltfläche Copy angezeigt. Sie sieht etwa so aus: https://your-site/wp-json/moyasar_p/v1/webhook. HTTP-Methode: POST.

Webhook shared secret: Tragen Sie denselben Wert ein wie das Shared secret des Webhooks in Moyasar. Lassen Sie das Feld leer und speichern Sie, um ein zufälliges Geheimnis zu erzeugen. Klicken Sie dann auf Show und kopieren Sie es nach Moyasar. Webhooks ohne das korrekte gemeinsame Geheimnis werden abgelehnt.

Wählen Sie für den Webhook diese Ereignisse aus:

payment_paid: der Kunde hat die Rechnung bezahlt.

payment_failed: die Zahlung ist fehlgeschlagen.

payment_refunded: die Zahlung wurde erstattet, zum Beispiel im Moyasar Dashboard.

payment_voided: die Zahlung wurde storniert.

Keinem Webhook und keiner Benachrichtigung wird direkt vertraut: Das Plugin ruft für jede davon die Rechnung über die Moyasar-API mit dem geheimen Schlüssel des Modus der Bestellung ab und prüft, dass sie für diese Bestellung erstellt wurde. Zahlungen anderer Integrationen auf demselben Moyasar-Konto werden ignoriert.

Bestellungen

Status after payment: der Bestellstatus nach einer bestätigten Zahlung. Der Status wird sofort gesetzt, ohne zweiten Statuswechsel.

Processing: der WooCommerce-Standard (Standard). Bestellungen mit nur virtuellen, herunterladbaren Produkten werden automatisch abgeschlossen.

Completed: jede bezahlte Bestellung wird Completed.

On hold: jede bezahlte Bestellung wartet auf Ihre manuelle Prüfung.

Erweitert

Debug log: Log API calls and notifications schreibt Details nach WooCommerce > Status > Logs, Quelle wcp_moyasar_payment_gateway. Fehler werden immer protokolliert. API-Schlüssel, Kartendaten und Kundendaten werden nie protokolliert. Standard: aus.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Zahlungsdaten, die in Bestellungen gespeichert sind (Moyasar-Rechnungs- und Zahlungs-IDs), bleiben erhalten, damit Erstattungen nachvollziehbar bleiben. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsart (standardmäßig Pay with Moyasar) und gibt die Bestellung auf. Das Plugin erstellt eine Moyasar-Rechnung über den Bestellbetrag in der Bestellwährung und leitet den Kunden zu deren Zahlungsseite weiter. Dort zahlt er mit einer beliebigen Methode, die in Ihrem Moyasar-Konto aktiv ist, zum Beispiel mada, Visa, Mastercard, Apple Pay oder STC Pay. Die Rechnung zeigt Order, die Bestellnummer und den Namen Ihrer Website.

Die Bestellung wird erst als bezahlt markiert, wenn Moyasar bestätigt: Das Plugin ruft die Rechnung über die Moyasar-API ab und prüft, dass sie bezahlt ist, zu dieser Bestellung gehört und genau den Bestellbetrag und die Bestellwährung hat. Nach der Zahlung kehrt der Kunde zur Seite „Bestellung eingegangen“ Ihres Shops zurück. Kommt der Kunde ohne Zahlung zurück (zum Beispiel über die Zurück-Schaltfläche der Zahlungsseite), gelangt er zur Kasse oder zur Seite Pay for order mit einer dieser Meldungen: The payment at Moyasar was not completed. You can try again or choose another payment method., Your Moyasar payment was declined or has expired. Please try again or choose another payment method. oder, wenn die Zahlung noch nicht geprüft werden kann, We could not confirm your payment with Moyasar yet. If you completed the payment, the order will be updated automatically in a few minutes — please check your e-mail before paying again.

Ein Kunde kann eine unbezahlte Bestellung erneut bezahlen. Ist die offene Zahlungsseite der Bestellung noch mit demselben Betrag und derselben Währung, wird sie wiederverwendet. Hat sich der Bestellbetrag geändert, wird die alte Zahlungsseite abgebrochen und eine neue erstellt, sodass die alte nicht mehr bezahlt werden kann. Ist die vorherige Rechnung bereits bezahlt, wird die Bestellung bestätigt, statt eine neue Zahlung anzulegen.

Kann Moyasar die Zahlung nicht starten, sieht der Kunde eine kurze Meldung, zum Beispiel The Moyasar payment service is not responding. Please try again in a few minutes., und kann eine andere Zahlungsart wählen. Die Details werden im Protokoll gespeichert.

Die Zahlungsart funktioniert an der klassischen Kasse, im Checkout-Block und auf der Seite Pay for order. Sie ist mit WooCommerce High-Performance Order Storage (HPOS) kompatibel.

Das Plugin verarbeitet Einmalzahlungen nur auf der Moyasar-Seite. Es gibt kein Kartenformular auf Ihrer eigenen Kasse, keine gespeicherten Karten oder Tokenisierung, keine WooCommerce Subscriptions und keine getrennte Autorisierung und Erfassung.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: die Rechnung wurde erstellt und der Kunde hat noch nicht bezahlt. Die Bestellnotiz zeigt die Rechnungs-ID, den Betrag und den Modus.

Processing, Completed or On hold: die Zahlung wurde bestätigt. Der Status richtet sich nach Status after payment. Die Bestellnotiz zeigt, wie die Zahlung bestätigt wurde (Webhook, Rechnungsbenachrichtigung, Rückkehr des Kunden oder Kasse), die Rechnungs-ID, die Zahlungs-ID und die Zahlungsart. Die Transaktions-ID ist die Moyasar-Zahlungs-ID.

On hold after payment: Moyasar hat einen anderen Betrag oder eine andere Währung gemeldet als den Bestellbetrag (die Bestellung ist nicht als bezahlt markiert), oder die Rechnung wurde bezahlt, nachdem die Bestellung storniert worden war. Die Bestellnotiz erklärt dies. Prüfen Sie die Zahlung im Moyasar Dashboard und erfüllen Sie die Bestellung oder erstatten Sie die Zahlung.

On hold before payment: Moyasar hält die Zahlung zur Prüfung zurück. Die Bestellung wird aktualisiert, sobald Moyasar entschieden hat.

Failed: die letzte Rechnung einer unbezahlten Bestellung ist fehlgeschlagen, abgelaufen oder storniert worden. Der Kunde kann erneut zu zahlen versuchen.

Cancelled: die Bestellung wurde vom Kunden, von Ihnen oder durch das Zeitlimit für die Lagerreservierung in WooCommerce storniert. Die offene Moyasar-Rechnung der Bestellung wird ebenfalls storniert, sodass sie nicht mehr bezahlt werden kann.

Eine bezahlte, stornierte oder erstattete Bestellung wird durch spätere Ereignisse nie verändert. Wird eine zweite Rechnung einer bereits bezahlten Bestellung bezahlt (zum Beispiel aus zwei Browser-Tabs), wird die Bestellung nicht erneut geändert. Eine Notiz fordert Sie auf, die doppelte Zahlung im Moyasar Dashboard zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Pay with Moyasar (die Schaltfläche verwendet den Titel der Zahlungsart). Vollständige und teilweise Erstattungen sind für Bestellungen mit einer Moyasar-Zahlung möglich. Eine vollständige Erstattung einer Kartenzahlung, die weniger als 2 Stunden zurückliegt, wird als Stornierung (Void, Abbruch vor der Abrechnung) gesendet; andernfalls ist es eine Erstattung. Die Erstattung verwendet den geheimen Schlüssel des Modus, in dem die Zahlung erfolgte (Test oder Live), daher muss dieser Schlüssel hinterlegt sein. Vor der Erstattung prüft das Plugin die Zahlung bei Moyasar: Währung, Status und den noch erstattbaren Betrag. Akzeptiert Moyasar die Erstattung nicht, zeigt WooCommerce den Fehler an, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung oder Stornierung wird in den Bestellnotizen vermerkt.

Im Moyasar Dashboard vorgenommene Erstattungen und Stornierungen gelangen über den Webhook zu Ihnen. Zeigt Moyasar mehr erstattet an als WooCommerce, wird der Bestellung eine Notiz hinzugefügt. Sie werden nicht automatisch als WooCommerce-Erstattungen erfasst. Erstellen Sie bei Bedarf eine manuelle Erstattung in WooCommerce ohne Refund via Pay with Moyasar.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzbereich befindet sich oben unter WooCommerce > Settings > Payments > Moyasar. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Bereich zeigt den Status, zum Beispiel das Datum, bis zu dem die Lizenz aktiv 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 den Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Moyasar 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 einrichten und testen können, bevor Sie einen Schlüssel kaufen. Auf der Plugins-Seite und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, doch für Updates und Support ist eine Verlängerung nötig. Der Status wird im Hintergrund automatisch erneut geprüft.

Fehlerbehebung

Moyasar erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, der aktuelle Modus einen geheimen Schlüssel hat (Test secret key im Testmodus, Live secret key im Live-Modus) und die Shop- oder Bestellwährung SAR, AED, USD, EUR, KWD, BHD oder OMR ist. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt oder die Währung nicht unterstützt wird.

Die Zahlung ist erfolgt, aber die Bestellung bleibt bei Pending payment: Die Bestätigungen haben Ihren Shop nicht erreicht. Richten Sie den Webhook ein: Prüfen Sie im Moyasar Dashboard, dass er existiert, dass seine URL genau der Webhook URL aus den Einstellungen entspricht, die Methode POST ist, alle vier Ereignisse ausgewählt sind und sein gemeinsames Geheimnis dem Webhook shared secret entspricht. Die Bestellung wird auch bestätigt, wenn der Kunde in den Shop zurückkehrt und wenn er versucht, dieselbe Bestellung erneut zu bezahlen.

Der Webhook antwortet Unauthorized: Das gemeinsame Geheimnis in Moyasar weicht vom Webhook shared secret ab. Klicken Sie auf Show, kopieren Sie den Wert und fügen Sie ihn im Webhook in Moyasar ein.

Der Webhook antwortet Webhook secret not configured: Die Einstellungen wurden noch nicht mit einem gemeinsamen Geheimnis gespeichert. Speichern Sie die Einstellungen, um eines zu erzeugen, und kopieren Sie es nach Moyasar.

Der Webhook antwortet Key not configured: Die Bestellung wurde in einem Modus (Test oder Live) bezahlt, dessen geheimer Schlüssel leer ist. Tragen Sie diesen Schlüssel ein.

Der Webhook antwortet Verification failed oder Try again later: Die Rechnung konnte nicht über die Moyasar-API gelesen werden, oder die Bestellung wurde zur gleichen Zeit von einer anderen Anfrage aktualisiert. Moyasar wiederholt den Webhook.

Fehler beim Speichern wegen des Schlüssels: Es wurde ein öffentlicher Schlüssel (pk_...) oder ein Schlüssel des anderen Modus eingefügt. Der bisherige Wert wurde beibehalten. Testschlüssel beginnen mit sk_test_, Live-Schlüssel mit sk_live_.

Der Kunde sieht beim Absenden der Bestellung einen Fehler: Aktivieren Sie Debug log und prüfen Sie WooCommerce > Status > Logs, Quelle wcp_moyasar_payment_gateway. This payment method is temporarily unavailable. Please choose another payment method or contact us. bedeutet meist einen falschen oder fehlenden geheimen Schlüssel. A payment for this order has already been received and is being reviewed. Please contact us instead of paying again. bedeutet, dass die Bestellung bereits eine bezahlte Rechnung hat, die Ihre Prüfung benötigt.

Die Bestellung ist On hold after payment: Lesen Sie die Bestellnotiz. Der bezahlte Betrag oder die Währung wich von der Bestellung ab, oder die Zahlung kam, nachdem die Bestellung storniert wurde. Erfüllen Sie die Bestellung oder erstatten Sie die Zahlung.

Die Erstattung schlägt fehl: Lesen Sie die Meldung. Wurde die Zahlung im anderen Modus getätigt, tragen Sie den geheimen Schlüssel dieses Modus ein. Ist der Betrag größer als der bei Moyasar noch erstattbare Betrag, wurde ein Teil der Zahlung bereits erstattet, zum Beispiel im Moyasar Dashboard. Hat Moyasar den erstatteten Betrag nicht bestätigt, prüfen Sie die Zahlung im Moyasar Dashboard, bevor Sie es erneut versuchen.

Der Lizenzbereich zeigt einen Fehler: Folgen Sie der Meldung im Bereich. Ist der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet, 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. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen und die Protokolle werden nur entfernt, wenn Clean uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Moyasar ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Moyasar verbunden noch wird es von Moyasar empfohlen.