VibeFox Moyasar for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul lässt sich auf älteren PHP-Versionen nicht installieren.

Währung: Die Warenkorbwährung muss SAR, AED, USD, EUR, KWD, BHD oder OMR sein. Bei jeder anderen Währung wird die Zahlungsmethode im Bestellvorgang ausgeblendet.

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

VibeFox-Lizenzschlüssel: Erhältlich auf vibefox.net. Ein Schlüssel funktioniert für eine Domain.

Installation

1. Gehen Sie im Back-Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls.

2. Klicken Sie nach Abschluss des Uploads auf Configure oder suchen Sie später VibeFox Moyasar Payment Gateway in der Modulliste und klicken Sie dort auf Configure.

3. Geben Sie Ihren VibeFox-Lizenzschlüssel im Feld License key im Lizenzblock oben auf der Seite Configure ein und klicken Sie auf Activate (siehe Lizenzschlüssel).

4. Fügen Sie Ihre geheimen Moyasar-Schlüssel ein und klicken Sie auf Save. Richten Sie den Webhook im Moyasar Dashboard ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Legen Sie im Testmodus eine Testbestellung an und deaktivieren Sie danach Test mode.

Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Moyasar payment und Moyasar payment on hold. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen finden Sie auf der Modulseite: Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn für den aktuellen Modus kein geheimer Schlüssel hinterlegt ist (die Zahlungsmethode wird dann im Bestellvorgang ausgeblendet), wenn kein geheimer Webhook-Schlüssel gespeichert ist (der Webhook weist dann jeden Aufruf ab) oder wenn die Standardwährung des Shops nicht unterstützt wird. Ist das Modul im Testmodus aktiviert, zeigt es Test mode is active: payments are simulated, no money is charged. Beim Speichern lehnt das Modul einen öffentlichen Schlüssel, einen Schlüssel des anderen Modus oder einen Schlüssel mit Leerzeichen ab, behält den bisherigen Wert bei und zeigt den Grund an.

Moyasar

Enable/Disable: Enable Moyasar schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: Der Name der Zahlungsmethode, den Kunden im Bestellvorgang sehen. Er wird auch als Zahlungsmethode in der Bestellung gespeichert. Standard: Pay with Moyasar. Pflichtfeld.

Description: Der Text, der im Bestellvorgang unter der Zahlungsmethode angezeigt wird. 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 der Bestellvorgang (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: verwendet den geheimen Testschlüssel: Zahlungen werden simuliert und es wird kein Geld abgebucht. Standard: ein. Deaktivieren Sie diese Option, 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_.

Gespeicherte Schlüssel und Geheimnisse werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie nur dann einen neuen Wert ein, wenn Sie ihn ändern möchten.

Zahlungsbenachrichtigungen (Webhook)

Der Webhook wird empfohlen, ist aber nicht zwingend erforderlich. Bestellungen werden auch bestätigt, wenn der Kunde in den Shop zurückkehrt, sowie durch die Rechnungsbenachrichtigung, die Moyasar automatisch an Ihren Shop sendet, sobald die Rechnung bezahlt ist. Der Webhook erfasst Kunden, die den Browser vor der Rückkehr schließen, und meldet Erstattungen, die im Moyasar Dashboard vorgenommen wurden. Hinterlegen Sie ihn unter Moyasar Dashboard > Settings > Webhooks.

Webhook URL: wird schreibgeschützt mit einer Schaltfläche Copy angezeigt. Mit suchmaschinenfreundlichen URLs sieht sie so aus: https://your-shop/module/wcp_moyasar_payment_gateway/webhook, gegebenenfalls mit einem Sprachkürzel wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen. HTTP-Methode: POST.

Webhook shared secret: Geben Sie denselben Wert ein wie Shared secret des Webhooks in Moyasar. Ist nichts gespeichert, erzeugt Save ein zufälliges Geheimnis; Generate a new secret ersetzt das gespeicherte. Ein erzeugtes Geheimnis wird nach dem Speichern einmalig oberhalb der Einstellungen angezeigt und danach nie wieder. Kopieren Sie es daher sofort in Moyasar. Webhooks ohne das richtige gemeinsame Geheimnis werden abgelehnt.

Wählen Sie für den Webhook diese Ereignisse aus (sie sind auch in diesem Abschnitt aufgelistet):

Einem Webhook oder einer Benachrichtigung wird nicht direkt vertraut: Das Modul ruft für jede Meldung die Rechnung über die Moyasar-API mit dem geheimen Schlüssel des Modus ab, in dem die Rechnung erstellt wurde, und prüft, ob sie für diesen Warenkorb erstellt wurde. Zahlungen anderer Integrationen auf demselben Moyasar-Konto werden ignoriert. Ein gemeinsames Geheimnis gilt für beide Modi.

Bestellungen

Status after payment: der Bestellstatus, der nach einer bestätigten Zahlung gesetzt wird. Die Bestellung wird direkt in diesem Status angelegt.

Erweitert

Clear saved secrets: Aktivieren Sie Test secret key, Live secret key oder Webhook shared secret und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Debug log: protokolliert API-Aufrufe und Benachrichtigungen in logs/moyasar_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Fehler und Warnungen werden immer protokolliert. API-Schlüssel, Kartendaten und Kundendaten werden nie protokolliert. Standard: aus.

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

Clean uninstall: Ist die Option aktiv, löscht die Deinstallation des Moduls die Moduleinstellungen und das Protokoll. Zahlungsdaten, die mit den Bestellungen gespeichert sind (Moyasar-Rechnungs- und Zahlungs-IDs), bleiben erhalten, damit Erstattungen nachvollziehbar bleiben. Standard: aus.

Bestellvorgang

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Pay with Moyasar) und bestätigt. Das Modul erstellt eine Moyasar-Rechnung über den Warenkorbbetrag in der Warenkorbwährung und leitet den Kunden auf deren Zahlungsseite weiter. Dort zahlt der Kunde mit einer beliebigen Methode, die in Ihrem Moyasar-Konto aktiv ist. Die Rechnung zeigt Order #, die Warenkorbnummer und den Namen Ihres Shops. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Die Bestellung wird erst als bezahlt markiert, wenn Moyasar die Zahlung bestätigt: Das Modul ruft die Rechnung über die Moyasar-API ab und prüft, ob sie bezahlt ist, zu diesem Warenkorb gehört und exakt den Warenkorbbetrag und die Warenkorbwährung hat. Danach wird die Bestellung angelegt, und der Kunde sieht die Standard-Bestellbestätigung mit Your payment with Moyasar has been received. Hält Moyasar die Zahlung zur Prüfung zurück, zeigt die Seite Your payment is being reviewed by Moyasar. The order will be updated automatically when Moyasar confirms it — please do not pay again. Ist die Bestellung zur Prüfung durch Sie auf Halten gesetzt, zeigt die Seite, dass die Zahlung eingegangen ist und die Bestellung geprüft wird. Schlägt eine geprüfte Zahlung später fehl oder wird die unbezahlte Bestellung storniert, zeigt die Seite Your Moyasar payment was not completed. Please contact us about this order.

Kehrt der Kunde ohne Zahlung zurück (zum Beispiel mit der Zurück-Schaltfläche der Zahlungsseite), befindet er sich wieder im Bestellvorgang und sieht eine 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. Der Warenkorb bleibt erhalten.

Der Kunde kann es erneut versuchen. Ist die offene Zahlungsseite des Warenkorbs noch mit demselben Betrag und derselben Währung gültig, wird sie wiederverwendet. Hat sich der Warenkorbbetrag geändert, wird die alte Zahlungsseite bei Moyasar storniert und eine neue erstellt, sodass die alte nicht mehr bezahlt werden kann. Stellt sich heraus, dass die vorherige Rechnung bereits bezahlt ist, wird stattdessen die Bestellung angelegt und keine neue Zahlung erzeugt.

Kann Moyasar die Zahlung nicht starten, bleibt der Kunde im Bestellvorgang mit einer kurzen Meldung, zum Beispiel The Moyasar payment service is not responding. Please try again in a few minutes., und kann eine andere Zahlungsmethode wählen. Die Details werden im Protokoll festgehalten.

Der Webhook und die Rechnungsbenachrichtigung funktionieren auch, wenn der Shop im Wartungsmodus ist, und werden nicht durch die Ländereinschränkung Ihres Shops blockiert.

Das Modul verarbeitet Einmalzahlungen nur auf der Moyasar-Seite. Es gibt kein Kartenformular in Ihrem eigenen Bestellvorgang, keine gespeicherten Karten oder Tokenisierung, keine Abonnements und keine getrennte Autorisierung und Erfassung.

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: Der Kunde wurde zu Moyasar geschickt und hat noch nicht bezahlt, oder Moyasar hat die Zahlung noch nicht bestätigt. Nur der Warenkorb existiert.

Payment accepted, Delivered oder Moyasar payment on hold: Die Zahlung wurde bestätigt. Der Status richtet sich nach Status after payment. Die Zahlung wird mit der Moyasar-Zahlungs-ID als Transaktions-ID erfasst. Eine Notiz zeigt, wie die Zahlung bestätigt wurde (Webhook, Rechnungsbenachrichtigung, Rückkehr des Kunden oder Bestellvorgang), sowie die Rechnungs-ID, die Zahlungs-ID und die Zahlungsmethode.

Awaiting Moyasar payment: Moyasar hält die Zahlung zur Prüfung zurück. Die Bestellung wechselt in den Bezahlt-Status, sobald Moyasar die Zahlung bestätigt.

Zahlungsfehler: Die Zahlung, die geprüft wird, ist fehlgeschlagen.

Moyasar payment on hold after payment: Moyasar hat einen anderen Betrag oder eine andere Währung gemeldet als den Warenkorbbetrag (zum Beispiel wurde der Warenkorb in einem anderen Tab geändert, nachdem die Zahlung begonnen hatte), oder die Rechnung wurde nach Ihrer Stornierung der Bestellung bezahlt. Die Bestellung wird nicht als bezahlt markiert, der tatsächlich eingegangene Betrag wird aber erfasst, wenn er in der Bestellwährung vorliegt. Die Notiz erklärt dies. Prüfen Sie die Zahlung im Moyasar Dashboard und wickeln Sie die Bestellung ab oder erstatten Sie die Zahlung.

Refunded: Die Zahlung wurde über das Modul vollständig erstattet.

Eine bezahlte Bestellung wird durch spätere Ereignisse nie wieder zurückgesetzt. Wird auch eine zweite Rechnung zu einem bereits bezahlten Warenkorb bezahlt (zum Beispiel aus zwei Browser-Tabs), bleibt die Bestellung unverändert. Eine Notiz bittet Sie, die doppelte Zahlung im Moyasar Dashboard zu erstatten.

Moyasar-Zahlungsblock

Die Bestellseite zeigt einen Block Moyasar payment mit der Moyasar-Rechnungs-ID, der Zahlungs-ID, der Methode (zum Beispiel Kartenmarke und die letzten vier Ziffern), dem Status, den bezahlten und erstatteten Beträgen, einem Abzeichen Test mode für Testzahlungen, dem Erstattungsverlauf und den Moyasar notes der Bestellung.

Erstattungen

Geben Sie im Block Moyasar payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Moyasar. Bestätigen Sie die Frage Refund this amount through Moyasar? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten; der Zugriff auf die Modulseiten ist nicht nötig. Erstattungen erfolgen in dem Betrag und der Währung, die Moyasar belastet hat. Nach einer Betragsabweichung können Sie daher bis zu dem erstatten, was der Kunde tatsächlich bezahlt hat, nicht den Bestellbetrag. Eine vollständige Erstattung einer Kartenzahlung, die weniger als 2 Stunden zurückliegt, wird als Stornierung (Void) gesendet (Abbruch vor der Abrechnung, ohne Gebühren). Andernfalls handelt es sich um eine Erstattung. Die Erstattung verwendet den geheimen Schlüssel des Modus, in dem die Zahlung erfolgt ist (Test oder Live). Dieser Schlüssel muss daher hinterlegt sein. Das Modul prüft bei Moyasar zuerst Währung, Status und erstattungsfähigen Betrag der Zahlung. Lehnt Moyasar die Erstattung ab, zeigt der Block die Fehlermeldung und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung oder Stornierung wird dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Moyasar die Zahlung bestätigt hat.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Moyasar zurück.

Im Moyasar Dashboard vorgenommene Erstattungen und Stornierungen gelangen über den Webhook zu Ihrem Shop. Zeigt Moyasar mehr erstattet an, als das Modul erfasst hat, wird der Bestellung eine Notiz hinzugefügt. Der Bestellstatus und die Gutschriften werden nicht automatisch geändert. Aktualisieren Sie sie bei Bedarf manuell, ohne Refund via Moyasar zu verwenden.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Moyasar Payment Gateway ist der erste Block auf Modules > Module Manager > VibeFox Moyasar Payment Gateway > Configure, oberhalb der Einstellungen. Geben Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den Schlüssel maskiert, den Status (zum Beispiel das Datum, bis zu dem die Lizenz gültig ist, und Ihre Domain) sowie die Schaltflächen Check now zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-moyasar und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Den Schlüssel können nur Mitarbeiter ändern, die das Recht Configure für das Modul haben. Die Texte des Blocks folgen der Sprache des Back Office (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 einen Domain-Platz in Ihrem Konto freigegeben haben, klicken Sie auf Check now. Ist der Lizenzserver nicht erreichbar, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-Einrichtung. 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 Moyasar Kunden im Bestellvorgang nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Die PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher ist die Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht im Bestellvorgang testen. Eine Erinnerung erscheint unter Modules > Module Manager auf der Registerkarte Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird während Ihrer Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Es ist kein Cron-Job nötig. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Moyasar erscheint nicht im Bestellvorgang: 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 Warenkorbwährung SAR, AED, USD, EUR, KWD, BHD oder OMR ist. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt oder die Shopwährung nicht unterstützt wird. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe zugelassen ist.

Die Zahlung war erfolgreich, aber es wurde keine Bestellung angelegt: 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, dass die Methode POST ist, dass die vier Ereignisse ausgewählt sind und dass sein gemeinsames Geheimnis dem in Webhook shared secret gespeicherten entspricht. Die Bestellung wird auch angelegt, wenn der Kunde in den Shop zurückkehrt oder versucht, denselben Warenkorb erneut zu bezahlen.

Der Webhook antwortet Unauthorized: Das gemeinsame Geheimnis in Moyasar weicht vom gespeicherten ab. Tragen Sie das Geheimnis des Moyasar-Webhooks in Webhook shared secret ein und speichern Sie, oder aktivieren Sie Generate a new secret, speichern Sie und fügen Sie das angezeigte Geheimnis in Moyasar ein.

Der Webhook antwortet Webhook secret not configured: Es ist kein gemeinsames Geheimnis gespeichert, zum Beispiel nachdem es mit Clear saved secrets entfernt wurde. Klicken Sie auf Save, um ein neues zu erzeugen, und kopieren Sie es in Moyasar.

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

Der Webhook antwortet Verification failed oder Try again later: Die Rechnung konnte nicht über die Moyasar-API gelesen werden, der Warenkorb wurde im selben Moment von einer anderen Anfrage aktualisiert oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). Moyasar wiederholt den Webhook. Aktivieren Sie Debug log, um den Grund zu sehen.

Die Webhook-URL zeigt im Browser Method not allowed: Das ist normal. Die URL akzeptiert nur POST-Anfragen von Moyasar.

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

Der Kunde sieht beim Wählen von Moyasar einen Fehler: Aktivieren Sie Debug log und sehen Sie sich das Feld Log auf der Modulseite an. 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 für den Warenkorb bereits eine bezahlte Rechnung vorliegt, die nicht in eine Bestellung umgewandelt werden konnte. Prüfen Sie das Protokoll.

Order is Moyasar payment on hold after payment: Lesen Sie die Moyasar notes im Block Moyasar payment. Der bezahlte Betrag oder die Währung wich vom Warenkorb ab, oder die Zahlung kam, nachdem die Bestellung storniert wurde. Wickeln Sie die Bestellung ab oder erstatten Sie die Zahlung.

Erstattung schlägt fehl: Lesen Sie die Meldung. Wurde die Zahlung im anderen Modus getätigt, geben Sie den geheimen Schlüssel dieses Modus ein. Ist der Betrag größer als der bei Moyasar noch erstattungsfähige 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.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Moyasar Payment Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Clean uninstall aktiv, werden die Moduleinstellungen und das Protokoll entfernt. Ist die Option deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Moyasar-Rechnungen, Zahlungen und Erstattungen sowie die Bestellstatus Awaiting Moyasar payment und Moyasar payment on hold bleiben immer erhalten, damit alte Bestellungen auch nach einer Neuinstallation erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Moyasar ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Moyasar verbunden und wird nicht von Moyasar unterstützt.