VibeFox Omise 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.

HTTPS: Die Kartenfelder befinden sich auf Ihrer Kassenseite, daher sollte die Kasse über HTTPS ausgeliefert werden. Kartendaten erreichen Ihren Server trotzdem nie. Omise sendet Webhooks nur an HTTPS-Adressen, und die 3-D-Secure-Seite der Bank muss eine HTTPS-Adresse sein.

Währung: eine von THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Bei einem Warenkorb in einer anderen Währung wird die Zahlungsart in der Kasse ausgeblendet.

Omise-Konto: Sie benötigen den öffentlichen und den geheimen Schlüssel Ihres Omise-Kontos für Test- und 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 im Back Office zu Modules > Module Manager und klicken Sie auf Upload a module. Wählen Sie die ZIP-Datei des Moduls.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Omise Payment in der Modulliste und klicken Sie auf Configure.

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

4. Tragen Sie Ihre Omise-Schlüssel für Test und Live ein und fügen Sie die auf der Einstellungsseite angezeigte Webhook-URL im Omise-Dashboard hinzu (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie eine Zahlung im Test-Modus mit einer Omise-Testkarte wie 4242 4242 4242 4242 und deaktivieren Sie danach Test mode.

Bei der Installation legt das Modul drei Bestellstatus an: Omise payment authorized, Omise payment on hold und Awaiting Omise payment. Die Zahlungsart wird für die Länder angeboten, die zum Zeitpunkt der Installation aktiv sind. Wenn Sie später weitere Länder aktivieren, erlauben Sie das Modul für sie unter Payment > Preferences; dort können Sie es auch nach Währung und Kundengruppe einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Omise Payment > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite Test mode is on — orders are charged with the test keys, no real money is moved., solange der Test-Modus aktiv ist. Außerdem warnt sie, wenn der öffentliche oder geheime Schlüssel des aktuellen Modus fehlt, und wenn Omise die Standardwährung Ihres Shops nicht akzeptiert. In diesen Fällen wird die Zahlungsart in der Kasse ausgeblendet.

Omise

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

Title: der Name der Zahlungsart, den der Kunde in der Kasse sieht. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: Credit / Debit Card. Pflichtfeld.

Description: der Text über dem Kartenformular in 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. Test-Schlü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 Test-Schlüssel in einem Live-Feld) nicht gespeichert: Der bisherige Wert bleibt erhalten, und eine Warnung wird angezeigt.

Test mode: verwendet die Test-Schlüssel, ohne echte Belastungen. Dabei werden beide Schlüssel umgeschaltet. Erfassungen, Erstattungen und Statusprüfungen einer Bestellung verwenden immer die Schlüssel des Modus, in dem die Bestellung bezahlt wurde. Standard: on.

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

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

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

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

Gespeicherte geheime Schlüssel 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.

Clear saved secrets: markieren Sie einen geheimen Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlung und Webhook

Webhook URL: die Adresse des Webhooks Ihres Shops. Mit suchmaschinenfreundlichen URLs sieht sie so aus: https://your-shop/module/wcp_omise_payment/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 Modul verarbeitet diese Ereignisse (sie sind auch in diesem Abschnitt aufgeführt):

charge.complete: eine Belastung wurde abgeschlossen, zum Beispiel nach 3-D Secure.

charge.capture: eine autorisierte Belastung wurde erfasst, auch wenn Sie sie im Omise-Dashboard erfassen.

charge.reverse: eine Autorisierung wurde storniert.

charge.expire: eine Belastung ist abgelaufen.

Omise signiert Webhooks nicht, daher wird der Webhook-Inhalt nie als vertrauenswürdig behandelt: Die Belastung muss von diesem Shop für diesen Warenkorb erstellt worden sein, und ihr Status wird mit dem geheimen Schlüssel des Modus der Zahlung erneut über die Omise-API abgerufen. Ohne Webhook wird eine Bestellung, deren Kunde den Browser während 3-D Secure schließt, nicht automatisch angelegt, und im Omise-Dashboard vorgenommene Erfassungen werden erst übernommen, wenn Sie auf Sync payment status klicken.

Payment action: was mit dem Kartenbetrag geschieht.

Capture immediately: der Betrag wird sofort belastet (Standard).

Authorize only (manual capture): die Karte wird nur autorisiert. Die Bestellung bleibt in Omise payment authorized, bis Sie im Omise-Block der Bestellung auf Capture payment klicken. Autorisierungen verfallen nach etwa 7 Tagen.

Per-charge webhook: sendet die Webhook-URL mit jeder Belastung. Nützlich, wenn mehrere Shops ein Omise-Konto teilen. Funktioniert nur, wenn der Shop HTTPS verwendet; andernfalls wird der Dashboard-Webhook genutzt. Standard: off.

Erweitert

Debug log: schreibt API-Anfragen und Zahlungsereignisse in logs/omise_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web lesen. Schlüssel, Token und Kartendaten werden nie protokolliert. Standard: off. Solange sie ausgeschaltet ist, wird nichts geschrieben, auch keine Fehler; schalten Sie sie daher ein, wenn Sie einem Problem nachgehen.

Log: zeigt die Größe und die neuesten Einträge des Protokolls, mit einer Schaltfläche zum Leeren.

Delete data on uninstall: wenn aktiviert, entfernt das Deinstallieren des Moduls die Einstellungen und das Debug-Protokoll. Die Omise-Belastungen und Erstattungen der Bestellungen sind Zahlungshistorie und bleiben immer erhalten. Standard: off.

Kasse

Im Zahlungsschritt wählt der Kunde 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 Test-Modus zeigt das Formular TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. Wenn der Kunde die Bestellung abschickt, macht Omise.js aus der Karte im Browser ein Einmal-Token und verwendet dafür die Rechnungsadresse des Warenkorbs. Die Kartenfelder werden nie an Ihren Shop übermittelt. Fehlende oder ungültige Felder werden unter dem Formular angezeigt, zum Beispiel Please enter a valid card number.

Ihr Shop erstellt die Belastung dann mit dem geheimen Schlüssel für die Warenkorbsumme in der Warenkorbwährung. Die Belastungsbeschreibung ist der Shopname und die Warenkorbnummer, und die Warenkorb-ID wird in den Metadaten der Belastung gespeichert. Zu diesem Zeitpunkt existiert noch keine Bestellung. Verlangt die Bank 3-D Secure, wird der Kunde zur Bankseite und zurück in Ihren Shop geleitet, und das Ergebnis wird 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 dem Warenkorb übereinstimmen. Der Kunde sieht die übliche Bestellbestätigungsseite mit Your card payment has been received. Bei Authorize only lautet die Seite Your card payment has been authorized. The amount will be charged when your order is processed. Meldet Omise die Zahlung noch als ausstehend, wird die Bestellung in Awaiting Omise payment angelegt, und die Seite zeigt Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. Kann die Zahlung direkt nach 3-D Secure nicht bestätigt werden, zeigt eine Seite Payment confirmation den Hinweis We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. und eine Schaltfläche Check again.

Wird die Karte abgelehnt, wird keine Bestellung angelegt. Der Kunde bleibt in 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 mit demselben Warenkorb erneut versuchen. Schlägt 3-D Secure fehl, ist der Kunde ebenfalls mit dem Grund zurück in der Kasse; ist die Belastung inzwischen abgelaufen oder storniert worden, lautet die Meldung The payment was not completed. Please try again.

Ein erneuter Versuch belastet nie doppelt: Ist die vorherige Belastung des Warenkorbs bereits bezahlt oder autorisiert, wird die Bestellung ohne neue Belastung angelegt. Ein nicht abgeschlossener 3-D-Secure-Versuch wird abgebrochen, bevor eine neue Belastung erfolgt. Ist für einen Warenkorb, der bereits eine Bestellung hat, noch eine zweite Belastung bezahlt (zum Beispiel in einem anderen Browser-Tab), bleibt die Bestellung unverändert, und eine Notiz fordert Sie auf, sie im Omise-Dashboard zu erstatten oder zu stornieren.

Der Webhook funktioniert auch, während der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.

Das Modul akzeptiert nur Karten. Es unterstützt keine anderen Omise-Zahlungsarten (PromptPay, TrueMoney, Mobile Banking, Ratenzahlungen), keine gespeicherten Karten oder Omise-Kunden, keine Abonnements und keine Teilerfassung.

Bestellungen und Erstattungen

Bestellstatus

No order yet: der Kunde ist bei 3-D Secure, oder die Karte wurde abgelehnt. Es existiert nur der Warenkorb.

Payment accepted: die Zahlung wurde bestätigt. Die Zahlung wird mit der Omise-Belastungs-ID (chrg_...) als Transaktions-ID erfasst, und eine Notiz zeigt den Betrag, die Belastung und wie sie bestätigt wurde (Kasse, Rückkehr von 3-D Secure, Webhook, Zahlungswiederholung, manuelle Erfassung oder manuelle Synchronisierung). Notizen sind private Nachrichten zur Bestellung und nur im Back Office sichtbar.

Omise payment authorized: die Karte wurde mit Authorize only autorisiert. Verwenden Sie Capture payment oder Void authorization.

Awaiting Omise payment: Omise hat die Zahlung noch nicht bestätigt. Der Webhook oder Sync payment status aktualisiert die Bestellung.

Omise payment on hold: Betrag oder Währung der Belastung weichen von der Bestellung ab, zum Beispiel weil der Warenkorb während 3-D Secure geändert wurde. Die Notiz zeigt beide Werte. Eine erfasste Zahlung wird trotzdem in der Bestellung verbucht. Prüfen Sie die Bestellung und bearbeiten Sie sie oder erstatten Sie die Zahlung.

Payment error: eine ausstehende Zahlung ist später fehlgeschlagen. Eine bezahlte Bestellung wird durch ein späteres fehlgeschlagenes Ereignis nie herabgestuft.

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

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

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

Omise-Zahlungsblock

Die Bestellseite zeigt einen Block Omise payment mit der Belastungs-ID, der Zahlungsaktion, dem Belastungsstatus, der Kartenmarke und den letzten Ziffern, den belasteten, bestellten und erstatteten Beträgen, einem Badge Test mode für Testzahlungen und dem Erstattungsverlauf. Die Schaltflächen des Blocks benötigen das Recht, Bestellungen zu bearbeiten, und den geheimen Schlüssel des Modus, in dem die Zahlung erfolgte. Zugriff auf die Module-Seiten ist nicht nötig. Das Ergebnis jeder Aktion wird oben im Block angezeigt.

Capture payment: erfasst den vollen autorisierten Betrag und setzt die Bestellung auf Payment accepted. Wird nur bei autorisierten Bestellungen angezeigt.

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

Sync payment status: liest die Belastung von Omise und aktualisiert die Bestellung. Die Notiz zeigt außerdem den bei Omise insgesamt erstatteten Betrag.

Erstattungen

Geben Sie im Block Omise payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Omise. Bestätigen Sie die Frage Refund this amount through Omise? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Erstattungen erfolgen in Betrag und Währung, die Omise belastet hat; nach einer Abweichung von Betrag oder Währung können Sie daher bis zu dem erstatten, was der Kunde tatsächlich bezahlt hat, nicht bis zur Bestellsumme. Die Erstattung wird im Modus der Zahlung gesendet, daher muss dessen geheimer Schlüssel gesetzt sein. Der Grund wird bei Omise zusammen mit der Erstattung gespeichert. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit der Omise-Erstattungs-ID hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine teilweise Erstattung ändert den Status nicht. Bei einer Autorisierung, die noch nicht erfasst wurde, ist nur eine vollständige Erstattung möglich, und sie storniert die Autorisierung. Lehnt Omise die Erstattung ab, zeigt der Block Refund failed. mit der Omise-Meldung, und es wird keine Erstattung verbucht.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Omise zurück. Im Omise-Dashboard vorgenommene Erstattungen werden nicht in PrestaShop erfasst; Sync payment status zeigt den erstatteten Gesamtbetrag.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Omise Payment ist der erste Block auf Modules > Module Manager > VibeFox Omise Payment > Configure, oberhalb der Einstellungen. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Danach zeigt der Block den maskierten Schlüssel, 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 zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-omise und der Link Manage licenses and domains in your account, der Ihr vibefox.net-Konto öffnet. Nur Mitarbeiter mit der Berechtigung Configure für das Modul können den Schlüssel ändern. 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. Nachdem sich die Adresse des Shops geändert hat oder Sie in Ihrem vibefox.net-Konto einen Domain-Platz 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 aktiven Schlüssel wird die Omise-Zahlungsart Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde Diese Zahlungsart ist nicht verfügbar. Bitte wählen Sie eine andere. Der PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind; daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, aber an der Kasse nicht 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 weiter.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird während der Arbeit im Back Office automatisch erneut geprüft: einmal täglich in den ersten 14 Tagen nach der 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

Omise does not appear at checkout: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, beide Schlüssel des aktuellen Modus eingetragen sind (Test-Schlüssel im Test-Modus, Live-Schlüssel sonst) und die Warenkorbwährung zu den unterstützten Währungen gehört. Die Einstellungsseite zeigt eine Warnung, wenn Schlüssel fehlen. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.

The payment went through, but no order was created or the order stays Awaiting Omise payment: der Webhook funktioniert nicht. Prüfen Sie im Omise-Dashboard, ob die Webhook-URL genau der unter Webhook URL angezeigten entspricht und HTTPS verwendet. Klicken Sie bei einer bestehenden Bestellung auf Sync payment status. Schalten Sie Debug log ein, um die Antworten des Webhooks zu sehen.

Webhook answers Charge ID does not match order or Order not found: die Belastung im Ereignis wurde nicht von diesem Shop für diesen Warenkorb erstellt. Es wird nichts geändert.

Webhook answers Order is being processed, retry later or Failed to verify charge: der Warenkorb wurde im selben Moment von einer anderen Anfrage gesperrt, die Omise-API war nicht erreichbar, oder der geheime Schlüssel des Zahlungsmodus fehlt. Omise wiederholt den Webhook.

Webhook answers The order could not be created, retry later: die Bestellung konnte nicht angelegt werden, zum Beispiel weil das Modul deaktiviert ist. Schalten Sie Debug log ein, um den Grund zu sehen.

The webhook URL shows Method not allowed in the browser: das ist normal. Die URL akzeptiert nur Anfragen von Omise.

Warning on save: key must start with ... or must be a live key: ein Schlüssel wurde in das falsche Feld eingefügt und nicht gespeichert. Test-Schlüssel beginnen mit pkey_test_ / skey_test_, Live-Schlüssel mit pkey_ / skey_.

The customer sees 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.

The customer sees We could not reach the payment provider: beim Erstellen der Belastung kam keine gültige Antwort von Omise. Eine Belastung wurde möglicherweise trotzdem erstellt; prüfen Sie das Omise-Dashboard, bevor der Kunde erneut bezahlt.

The customer sees This order is already being paid: die Kasse wurde im selben Moment zweimal abgeschickt. Der Kunde wartet kurz und prüft die E-Mail, bevor er es erneut versucht.

Order is Omise payment on hold after payment: lesen Sie die Notiz in der Bestellung (siehe Bestellstatus) und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Refund fails with a message about the mode: die Zahlung erfolgte im Test- oder Live-Modus, und der geheime Schlüssel dieses Modus ist nicht gesetzt. Tragen Sie ihn ein und versuchen Sie es erneut.

Partial refund of an authorized order fails: die Zahlung ist nur autorisiert. Erfassen Sie sie zuerst oder erstatten Sie den vollen Betrag, um sie zu stornieren.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Omise Payment und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall aktiv, werden die Einstellungen und das Debug-Protokoll entfernt. Ist es aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Omise-Belastungen und Erstattungen sowie die Bestellstatus Omise payment authorized, Omise payment on hold und Awaiting Omise payment bleiben immer erhalten, sodass bereits bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Omise ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Omise verbunden noch von Omise empfohlen.