VibeFox ePay.bg for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv.

PHP: 8.0 oder neuer.

Shop-Währung: Bulgarischer Lew (BGN), Euro (EUR) oder US-Dollar (USD). Die Bestellung wird in ihrer eigenen Währung mit 2 Dezimalstellen abgerechnet. Bei anderen Währungen wird die Zahlungsmethode an der Kasse ausgeblendet.

ePay.bg-Konto: Sie benötigen die Kundennummer (MIN) und den geheimen Schlüssel aus Ihrem ePay.bg-Händlerprofil: die Live-Daten von www.epay.bg, die Testdaten von demo.epay.bg (ein Testkonto wird separat registriert). Außerdem müssen Sie die Benachrichtigungs-URL Ihres Shops im Händlerprofil eintragen.

VibeFox-Lizenzschlüssel: bei vibefox.net erworben. Ein Schlüssel gilt für eine 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 den Ordner wcp_epaybg_gateway auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate. WooCommerce muss aktiv sein.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > ePay.bg > 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. Geben Sie die MIN und den geheimen Schlüssel für Test und/oder Live ein (siehe Konfiguration).

6. Kopieren Sie die im Abschnitt Payment notifications (IPN) angezeigte Benachrichtigungs-URL in das Feld URL for receiving notifications des ePay.bg-Händlerprofils, sowohl im Demo- als auch im Live-Profil. Ohne sie bleiben Bestellungen auf „Zahlung ausstehend“.

7. Aktivieren Sie Enable/Disable. Geben Sie im Testmodus eine Testbestellung auf und deaktivieren Sie dann Test Mode.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > ePay.bg. Über den Feldern zeigt die Seite einen Fehler an, wenn die Shop-Währung nicht BGN, EUR oder USD ist, eine Warnung, wenn das Gateway aktiviert ist, aber die MIN oder der geheime Schlüssel des gewählten Modus leer ist (es wird dann an der Kasse ausgeblendet, und beim Speichern erscheint derselbe Fehler), sowie Test mode is on: payments go to demo.epay.bg and no real money is charged., solange der Testmodus aktiv ist. In der Liste der Zahlungsmethoden ist ePay.bg als einrichtungsbedürftig markiert, bis die Zugangsdaten des gewählten Modus eingegeben sind.

Allgemein

Enable/Disable: Enable ePay.bg Payment Gateway schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: ePay.bg.

Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely via ePay.bg with a bank card or your ePay.bg account.

ePay.bg-Konto

Die Kundennummer (MIN) und der geheime Schlüssel werden in Ihrem Händlerprofil auf www.epay.bg (Live) und demo.epay.bg (Testkonto, separat registriert) angezeigt. Leerzeichen und Zeilenumbrüche in eingefügten geheimen Schlüsseln werden beim Speichern entfernt.

Test Mode: Enable test mode (use demo.epay.bg and the test credentials). Wenn aktiv, werden Kunden in die ePay.bg-Demoumgebung weitergeleitet, und die Anforderungen werden mit den Testzugangsdaten signiert. Standard: ein.

Test Merchant ID (MIN): die Kundennummer (MIN) Ihres demo.epay.bg-Händlerkontos.

Test Secret Key: der geheime Schlüssel Ihres demo.epay.bg-Händlerkontos (64 Zeichen).

Live Merchant ID (MIN): die Kundennummer (MIN) Ihres www.epay.bg-Händlerkontos.

Live Secret Key: der geheime Schlüssel Ihres www.epay.bg-Händlerkontos (64 Zeichen), der für die HMAC-SHA1-Signatur verwendet wird.

Wenn Sie von Version 1.0 aktualisieren, wird der einzelne Zugangsdatensatz dieser Version in die Testfelder übernommen, sofern der Testmodus aktiv war.

Zahlungsbenachrichtigungen (IPN)

Die Benachrichtigung teilt Ihrem Shop mit, dass eine Zahlungsanforderung bezahlt oder abgelehnt wurde oder abgelaufen ist. Dieser Abschnitt zeigt die Benachrichtigungs-URL. Sie sieht so aus: https://your-site/wc-api/epaybg_payment_callback/. Tragen Sie sie als URL for receiving notifications im ePay.bg-Händlerprofil ein, für Live und Test. Bestellungen werden nur durch diese signierten Benachrichtigungen als bezahlt markiert; die Rückkehr des Kunden in den Shop markiert eine Bestellung nicht als bezahlt.

ePay.bg meldet für jede Rechnung diese Ergebnisse:

PAID: der Kunde hat bezahlt. Die Bestellung wird als bezahlt markiert.

DENIED: die Zahlung wurde abgelehnt. Die unbezahlte Bestellung wird storniert.

EXPIRED: die Zahlungsanforderung ist unbezahlt abgelaufen. Die unbezahlte Bestellung wird storniert.

Jede Benachrichtigung wird mit dem geheimen Schlüssel des gewählten Modus geprüft. Benachrichtigungen ohne gültige Prüfsumme werden abgelehnt, und ePay.bg sendet sie weiter. Ohne die Benachrichtigungs-URL im Händlerprofil wird keine Bestellung als bezahlt markiert.

Zahlungsanforderung

Invoice Prefix: nur Ziffern (bis zu 10), die der Bestell-ID vorangestellt werden und die ePay.bg-Rechnungsnummer bilden, zum Beispiel 00001 + 123 = 00001123. Verwenden Sie für verschiedene Shops auf einem ePay.bg-Konto unterschiedliche Präfixe. Andere Zeichen werden beim Speichern entfernt. Das spätere Ändern des Präfixes ist unbedenklich: Ausstehende Bestellungen werden anhand der an der Bestellung gespeicherten Rechnung gefunden. Standard: 00001.

Expiration Time: die Zeit, nach der eine unbezahlte Zahlungsanforderung abläuft; ePay.bg meldet sie dann als abgelaufen, und die ausstehende Bestellung wird storniert. Wählen Sie 1, 3, 6, 12, 24, 48 oder 72 Stunden. Die Zeit wird in bulgarischer Zeit gesendet, unabhängig von der Zeitzone Ihrer Website. Standard: 24 Stunden.

Language: die Sprache der ePay.bg-Zahlungsseite, Englisch oder Bulgarisch. Standard: Englisch.

Order Status After Payment: der Bestellstatus, der nach einer erfolgreichen Zahlung gesetzt wird. Der Status wird sofort gesetzt, ohne zweiten Statuswechsel.

Default (WooCommerce decides): In Bearbeitung oder Abgeschlossen bei Bestellungen mit ausschließlich virtuellen herunterladbaren Produkten (Standard).

Processing: jede bezahlte Bestellung wird auf „In Bearbeitung“ gesetzt.

Completed: jede bezahlte Bestellung wird auf „Abgeschlossen“ gesetzt.

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

Erweitert

Logging: Enable logging schreibt Zahlungsanforderungen und Benachrichtigungen in WooCommerce > Status > Logs, Quelle wcp_epaybg_gateway, ohne geheime Schlüssel oder Kartendaten. Standard: aus.

Delete Data on Uninstall: Remove all plugin data when uninstalled. Wenn aktiviert, werden beim Deinstallieren des Plugins die Gateway-Einstellungen, die an Bestellungen gespeicherten ePay.bg-Daten und die Plugin-Protokolle gelöscht. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig ePay.bg) und gibt die Bestellung auf. Der Kunde sieht Redirecting to ePay.bg for payment... und wird mit einer signierten Zahlungsanforderung über den Bestellbetrag in der Bestellwährung, mit Rechnungsnummer und Ablaufzeit, zu ePay.bg weitergeleitet. Die Seite enthält außerdem die Schaltfläche Pay via ePay.bg, falls die Weiterleitung nicht startet, und die Schaltfläche Cancel order. Bei ePay.bg zahlt der Kunde mit einer Bankkarte oder einem ePay.bg-Konto.

Nach der Zahlung kehrt der Kunde auf die Bestellbestätigungsseite Ihres Shops zurück. Die Bestellung wird erst als bezahlt markiert, wenn die signierte ePay.bg-Benachrichtigung eintrifft. Der Warenkorb wird erst auf der Bestellbestätigungsseite geleert.

Bricht der Kunde bei ePay.bg ab, wird die Bestellung auf die übliche WooCommerce-Weise storniert und der Warenkorb bleibt erhalten, sodass der Kunde eine andere Zahlungsmethode wählen kann.

Kann die Bestellung nicht mit ePay.bg bezahlt werden, sieht der Kunde eine kurze Meldung, zum Beispiel ePay.bg payments are temporarily unavailable. Please choose another payment method. oder den Hinweis, dass ePay.bg keine Zahlungen in der Bestellwährung akzeptiert.

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 unterstützt nur Einmalzahlungen bei ePay.bg. Es bietet keine Erstattungen aus WooCommerce, keine gespeicherten Karten oder Tokenisierung, keine Abonnements oder wiederkehrenden Zahlungen und keine EasyPay- oder B-Pay-Barzahlungscodes.

Bestellungen

Bestellstatus

Pending payment: der Kunde wurde zu ePay.bg weitergeleitet und hat noch nicht bezahlt, oder die Benachrichtigung ist noch nicht eingetroffen. Die Bestellnotiz lautet Awaiting ePay.bg payment.

Processing, Completed or On Hold: die Zahlung wurde bestätigt. Der Status folgt der Einstellung Order Status After Payment. Die Bestellnotiz zeigt die Rechnungsnummer, das Zahlungsdatum, die STAN und den BORICA-Code. Die Transaktions-ID ist die STAN (oder die Rechnungsnummer, wenn es keine STAN gibt).

On hold after payment: die Zahlung ist eingegangen, aber nicht für das, was die Bestellung jetzt angibt: Gesamtbetrag oder Währung wurden nach der Zahlungsanforderung geändert, die Anforderung wurde im anderen Modus gestellt oder das Gateway wurde danach zwischen Test und Live umgeschaltet, die Zahlungsmethode der Bestellung wurde geändert, oder die Bestellung war zuvor storniert worden. Die Bestellnotiz nennt den Grund. Prüfen Sie die Zahlung im ePay.bg-Händlerbereich und schließen Sie die Bestellung manuell ab oder erstatten Sie sie.

Cancelled: ePay.bg hat die Zahlungsanforderung als abgelehnt oder abgelaufen gemeldet, oder der Kunde hat bei ePay.bg abgebrochen. WooCommerce stellt den Bestand wieder her. Eine stornierte Bestellung kann nicht erneut bezahlt werden, weil die ePay.bg-Rechnungsnummer aus Präfix und Bestell-ID besteht. Der Kunde gibt eine neue Bestellung auf.

Eine verspätete Ablehnungs- oder Ablaufmeldung ändert eine bezahlte Bestellung nie. Geht eine Zahlung für eine bereits bezahlte oder erstattete Bestellung ein, wird der Status nicht geändert, und eine Notiz fordert Sie auf, im ePay.bg-Händlerbereich auf eine Doppelzahlung zu prüfen.

Erstattungen

Erstattungen aus WooCommerce sind nicht verfügbar, weil die ePay.bg-WEB-API keinen Erstattungsaufruf hat. Erstatten Sie die Zahlung im ePay.bg-Händlerbereich und erfassen Sie die Erstattung manuell in WooCommerce.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben auf WooCommerce > Settings > Payments > ePay.bg. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Block zeigt den Status an, 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 gilt für eine 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 ePay.bg Kunden an der Kasse nicht angezeigt. Wird eine Zahlung dennoch gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsmethode weiterhin, gekennzeichnet mit (unlicensed — visible to admins only), sodass Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Auf der Plugin-Seite und auf WooCommerce-Seiten erscheint ein Hinweis. Bestehende Bestellungen sind nicht betroffen: bereits gestartete Zahlungen werden weiterhin bestätigt.

Wenn eine Lizenz abläuft, funktioniert das Plugin weiter, aber Updates und Support erfordern eine Verlängerung. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

ePay.bg erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, die MIN und der geheime Schlüssel des gewählten Modus eingetragen sind und die Shop-Währung BGN, EUR oder USD ist. Die Einstellungsseite zeigt in jedem dieser Fälle eine Warnung an.

Die Zahlung ging durch, aber die Bestellung bleibt auf „Zahlung ausstehend“: Die Bestellung wird nur durch die ePay.bg-Benachrichtigung als bezahlt markiert. Prüfen Sie, ob die Benachrichtigungs-URL im ePay.bg-Händlerprofil des verwendeten Modus (Demo oder Live) eingetragen ist und ob der geheime Schlüssel des aktiven Modus stimmt. Aktivieren Sie Logging und sehen Sie unter WooCommerce > Status > Logs nach, Quelle wcp_epaybg_gateway.

Die Benachrichtigung antwortet ERR=Not valid CHECKSUM: Der geheime Schlüssel in den Einstellungen passt nicht zum Händlerprofil, das die Benachrichtigung gesendet hat. Benachrichtigungen werden mit dem Schlüssel des aktuell gewählten Modus und dann mit dem Schlüssel des anderen Modus geprüft, sodass vor dem Moduswechsel gestellte Zahlungsanforderungen weiterhin akzeptiert werden. ePay.bg versucht es weiter, sodass die Bestellung aktualisiert wird, sobald der Schlüssel stimmt.

Die Benachrichtigung antwortet ERR=Not configured: Der geheime Schlüssel des gewählten Modus ist leer. Tragen Sie ihn ein.

Die Benachrichtigung antwortet STATUS=NO für eine Rechnung: Die Rechnung gehört nicht zu einer ePay.bg-Bestellung dieses Shops, zum Beispiel weil sie von einem anderen Shop auf demselben ePay.bg-Konto ausgestellt wurde. Geben Sie jedem Shop ein eigenes Invoice Prefix.

Die Benachrichtigung antwortet STATUS=ERR: ein vorübergehender Fehler, zum Beispiel zwei Benachrichtigungen für dieselbe Bestellung im selben Moment. ePay.bg sendet die Benachrichtigung erneut.

Die Bestellung ist nach der Zahlung „In Wartestellung“: Lesen Sie die Bestellnotiz. Gesamtbetrag oder Währung haben sich nach der Zahlungsanforderung geändert, die Anforderung wurde im anderen Modus gestellt oder der Modus wurde danach umgeschaltet, die Zahlungsmethode hat sich geändert oder die Bestellung war storniert worden. Prüfen Sie die Zahlung im ePay.bg-Händlerbereich.

Das Rechnungspräfix wurde beim Speichern geändert: Das Präfix darf nur Ziffern enthalten, bis zu 10. Andere Zeichen werden entfernt.

Der Lizenzblock zeigt einen Fehler an: 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 Website-Adresse 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.

Für Entwickler: Die Readme erwähnt den Filter epay_bp_form_fields, zum Beispiel um die direkte Kartenseite (PAGE=credit_paydirect) zu verwenden.

Deinstallation

Beim Deaktivieren des Plugins bleiben alle Daten erhalten. 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, die an Bestellungen gespeicherten ePay.bg-Daten und die Protokolle werden nur entfernt, wenn Delete Data on Uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

ePay.bg ist eine Marke des jeweiligen Inhabers. Dieses Plugin steht in keiner Verbindung zu ePay.bg und wird von ePay.bg nicht unterstützt.