VibeFox ePay.bg 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: bulgarischer Lew (BGN), Euro (EUR) oder US-Dollar (USD). Der Warenkorb wird in seiner eigenen Währung mit 2 Nachkommastellen belastet. Bei Warenkörben in anderen Währungen wird die Zahlungsart an der Kasse nicht angezeigt.

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: 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. Klicken Sie nach dem Upload auf Configure, oder suchen Sie später VibeFox ePay.bg Gateway 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. Geben Sie MIN und geheimen Schlüssel für Test und/oder Live ein (siehe Konfiguration).

5. Kopieren Sie die URL aus dem Abschnitt Payment notifications (IPN) in das Feld URL for receiving notifications im ePay.bg-Händlerprofil, sowohl im Demo- als auch im Live-Profil. Ohne diese URL wird keine Bestellung angelegt.

6. 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 den Bestellstatus ePay.bg payment on hold an. PrestaShop bietet das neue Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox ePay.bg Gateway > Configure. Jede Schaltfläche Save speichert die gesamte Seite. Oberhalb der Felder zeigt die Seite einen Fehler, wenn die Standardwährung des Shops nicht BGN, EUR oder USD ist, eine Warnung, wenn das Gateway aktiviert ist, aber MIN oder geheimer Schlüssel des gewählten Modus leer sind (das Gateway wird dann an der Kasse ausgeblendet, und beim Speichern erscheint dieselbe Warnung), und Test mode is on: payments go to demo.epay.bg and no real money is charged. während der Testmodus aktiviert ist.

ePay.bg

Enable/Disable: Enable ePay.bg Payment Gateway aktiviert oder deaktiviert die Zahlungsart. Standard: aus.

Title: der Name der Zahlungsart, den Kunden an der Kasse sehen. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: ePay.bg. Pflichtfeld.

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

ePay.bg-Konto

Kundennummer (MIN) und geheimer Schlüssel stehen in Ihrem Händlerprofil auf www.epay.bg (live) und demo.epay.bg (Testkonto, separat registriert).

Test Mode: aktiviert den Testmodus. Kunden werden an die Demo-Umgebung von ePay.bg geleitet, und die Anforderungen werden mit den Testzugangsdaten signiert. Standard: an.

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

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

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

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

Gespeicherte geheime Schlüssel werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie einen neuen Wert nur ein, wenn Sie ihn ändern möchten. Leerzeichen und Zeilenumbrüche in eingefügten Schlüsseln werden beim Speichern entfernt.

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

Payment notifications (IPN)

Die Benachrichtigung teilt Ihrem Shop mit, dass eine Zahlungsanforderung bezahlt, abgelehnt wurde oder abgelaufen ist. Das Feld Notification URL zeigt die URL, die Sie als URL for receiving notifications im ePay.bg-Händlerprofil eintragen, für Live und Test. Bei aktivierten suchmaschinenfreundlichen URLs sieht sie so aus: https://your-shop/module/wcp_epaybg_gateway/notify, gegebenenfalls mit einem Sprachcode wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen. Bestellungen werden nur durch diese signierten Benachrichtigungen angelegt; die Rückkehr des Kunden in den Shop legt keine Bestellung an und bezahlt keine.

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

Benachrichtigungen ohne gültige Prüfsumme werden abgelehnt, und ePay.bg sendet sie weiter. Die Prüfsumme wird mit dem geheimen Schlüssel jedes Modus geprüft, der einen hat, sodass Zahlungen, die vor dem Wechsel zwischen Test und Live gestartet wurden, weiterhin bestätigt werden. Eine Zahlung muss in dem Modus eingehen, in dem die Anforderung gestellt wurde; andernfalls wird die Bestellung auf ePay.bg payment on hold gesetzt. Ohne die Benachrichtigungs-URL im Händlerprofil wird keine Bestellung angelegt.

Payment request

Invoice Prefix: nur Ziffern (bis zu 10), die vor die Warenkorb-ID gesetzt werden und so die ePay.bg-Rechnungsnummer bilden, zum Beispiel 00001 + 123 = 00001123. Verwenden Sie unterschiedliche Präfixe für verschiedene Shops auf einem ePay.bg-Konto. Andere Zeichen werden beim Speichern mit einer Warnung entfernt. Das spätere Ändern des Präfixes ist unbedenklich: offene Zahlungsanforderungen werden über die dafür gespeicherte Rechnung gefunden. Standard: 00001.

Expiration Time: die Zeit, nach der eine unbezahlte Zahlungsanforderung abläuft; ePay.bg meldet sie dann als abgelaufen, und es wird keine Bestellung angelegt. Wählen Sie 1, 3, 6, 12, 24, 48 oder 72 Stunden. Die Zeit wird in bulgarischer Zeit übermittelt, unabhängig von der Zeitzone Ihres Shops. 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.

Advanced

Logging: schreibt Zahlungsanforderungen und Benachrichtigungen in logs/epay_bp_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Geheime Schlüssel und Kartendaten werden nicht protokolliert. Standard: aus. Fehler werden immer protokolliert, auch wenn es ausgeschaltet ist.

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

Delete Data on Uninstall: ist es aktiviert, entfernt die Deinstallation des Moduls die Gateway-Einstellungen und das Protokoll. Die ePay.bg-Zahlungsdatensätze, der Bestellstatus ePay.bg payment on hold und die Bestellungen bleiben immer erhalten. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig ePay.bg) und bestätigt. Der Kunde sieht Redirecting to ePay.bg for payment... und wird mit einer signierten Zahlungsanforderung über den Warenkorbbetrag in der Warenkorbwährung, mit der Rechnungsnummer und der Ablaufzeit an ePay.bg weitergeleitet. Auf ePay.bg erscheint die Zahlung als Cart mit der Warenkorbnummer. Die Seite enthält außerdem eine Schaltfläche Pay via ePay.bg, falls die Weiterleitung nicht startet, und eine Schaltfläche Cancel. Auf ePay.bg zahlt der Kunde mit einer Bankkarte oder einem ePay.bg-Konto. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst angelegt, wenn die signierte Benachrichtigung von ePay.bg eintrifft. Ist sie bereits eingetroffen, sieht der Kunde die übliche Bestellbestätigungsseite. Falls nicht, zeigt eine Seite Payment confirmation den Text Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. mit den Schaltflächen Check again und Back to checkout.

Bricht der Kunde bei ePay.bg ab, kehrt er zur Kasse zurück und sieht The ePay.bg payment was cancelled. You can try again or choose another payment method. Hat ePay.bg die Anforderung als abgelehnt oder abgelaufen gemeldet, lautet die Meldung The payment was not completed. You can try again or choose another payment method. Der Warenkorb bleibt erhalten. Ein neuer Versuch für denselben Warenkorb verwendet dieselbe Rechnungsnummer.

Lässt sich der Warenkorb nicht mit ePay.bg bezahlen, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel ePay.bg payments are temporarily unavailable. Please choose another payment method. oder dass ePay.bg keine Zahlungen in der Warenkorbwährung annimmt.

Die Benachrichtigung funktioniert, während der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.

Das Modul nimmt nur Einmalzahlungen über ePay.bg an. Es gibt keine Erstattungen aus PrestaShop, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen und keine EasyPay- oder B-Pay-Barzahlungscodes.

Bestellungen

Bestellstatus

No order yet: der Kunde wurde zu ePay.bg geleitet und hat nicht bezahlt, die Benachrichtigung ist noch nicht eingetroffen, oder ePay.bg hat die Anforderung als abgelehnt oder abgelaufen gemeldet. Es existiert nur der Warenkorb.

Payment accepted, Delivered or ePay.bg payment on hold: die Zahlung wurde bestätigt. Der Status richtet sich nach Order Status After Payment. Die Zahlung wird mit dem STAN als Transaktions-ID erfasst (oder mit der Rechnungsnummer, falls kein STAN vorhanden ist), und eine Notiz zeigt die Rechnungsnummer, das Zahlungsdatum, den STAN und den BORICA-Code.

ePay.bg payment on hold after payment: die Zahlung ist eingegangen, passt aber nicht zu dem, was der Warenkorb jetzt aussagt: Der Warenkorbbetrag oder die Währung wurde nach der Zahlungsanforderung geändert, oder die Benachrichtigung kam in einem anderen Modus (Test oder Live) als die Anforderung. Die Zahlung wird nicht als bezahlt erfasst. Dasselbe geschieht, wenn der Warenkorb bereits eine unbezahlte Bestellung hat, zum Beispiel eine stornierte oder eine mit einer anderen Zahlungsart. Die Notiz erklärt den Grund. Prüfen Sie die Zahlung im ePay.bg-Händlerbereich und bearbeiten oder erstatten Sie die Bestellung manuell.

Geht eine Zahlung für eine bereits bezahlte oder erstattete Bestellung ein, bleibt der Status unverändert, und eine Notiz fordert Sie auf, im ePay.bg-Händlerbereich nach einer Doppelzahlung zu suchen. Eine verspätete Ablehnungs- oder Ablaufmeldung ändert nie eine bezahlte Bestellung.

ePay.bg-Zahlungsblock

Die Bestellseite zeigt einen Block ePay.bg payment mit Rechnung, angefragtem Betrag und Währung, Ergebnis der Benachrichtigung, Zahlungsdatum, STAN, BORICA-Code, einem Abzeichen Test mode für Testzahlungen und den ePay.bg notes der Bestellung.

Erstattungen

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

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox ePay.bg Gateway ist der erste Block auf Modules > Module Manager > VibeFox ePay.bg 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 aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um den Schlüssel aus diesem Shop zu entfernen. Darunter stehen die Zeile Product: presta-payment-epaybg 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 Backoffice (Englisch und Russisch sind enthalten).

Wird der Schlüssel nicht akzeptiert, zeigt der Block den Grund an, 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. Kann der Lizenzserver nicht erreicht werden, arbeitet das Modul mit dem zuletzt bekannten Status weiter.

Ein Schlüssel funktioniert für eine Domain: die Domain des Hauptshops, auch in einem Multistore-Setup. 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 ePay.bg Kunden an der Kasse nicht angezeigt. Wird dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Der PrestaShop-Storefront weiß nicht, dass Sie im Backoffice angemeldet sind, daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt.

Läuft eine Lizenz ab, arbeitet das Modul weiter, aber Updates und Support benötigen eine Verlängerung. Der Status wird während Ihrer Arbeit im Backoffice 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

ePay.bg erscheint nicht an der Kasse: prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, MIN und geheimer Schlüssel des gewählten Modus gesetzt sind und die Warenkorbwährung BGN, EUR oder USD ist. Die Einstellungsseite zeigt eine Warnung, wenn Zugangsdaten fehlen. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.

Die Zahlung ist durchgegangen, aber es wurde keine Bestellung angelegt: die Bestellung wird nur durch die Benachrichtigung von ePay.bg angelegt. Prüfen Sie, ob die Benachrichtigungs-URL im ePay.bg-Händlerprofil des verwendeten Modus (Demo oder Live) genau so eingetragen ist, wie sie unter Notification URL angezeigt wird, und ob der geheime Schlüssel dieses Modus stimmt. Sehen Sie im Feld Log auf der Modulseite nach; aktivieren Sie Logging, um jede Benachrichtigung zu sehen.

Die Benachrichtigung antwortet ERR=Not valid CHECKSUM: kein gespeicherter geheimer Schlüssel passt zum Händlerprofil, das die Benachrichtigung gesendet hat. ePay.bg versucht es weiter, daher wird die Bestellung angelegt, sobald der Schlüssel stimmt.

Die Benachrichtigung antwortet ERR=Not configured: es ist kein geheimer Schlüssel gespeichert. Geben Sie ihn ein.

Die Benachrichtigung antwortet STATUS=NO für eine Rechnung: die Rechnung wurde nicht von diesem Shop ausgestellt, zum Beispiel von einem anderen Shop auf demselben ePay.bg-Konto. Geben Sie jedem Shop ein eigenes Invoice Prefix.

Die Benachrichtigung antwortet STATUS=ERR: ein vorübergehender Fehler, zum Beispiel zwei Benachrichtigungen für denselben Warenkorb im selben Moment oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). ePay.bg sendet die Benachrichtigung erneut. Der Grund steht im Protokoll.

Die Benachrichtigungs-URL zeigt ERR=Method not allowed in the browser: das ist normal. Die URL akzeptiert nur Anfragen von ePay.bg.

Bestellung ist nach der Zahlung ePay.bg payment on hold: lesen Sie die Notizen im Block ePay.bg payment (siehe Bestellstatus), prüfen Sie die Zahlung im ePay.bg-Händlerbereich und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung dort.

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

Für Entwickler erwähnt die Readme den Hook actionEpayBpFormFields (den Filter epay_bp_form_fields der WooCommerce-Version), zum Beispiel um die direkte Kartenseite (PAGE=credit_paydirect) zu verwenden.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox ePay.bg Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete Data on Uninstall aktiviert, werden die Gateway-Einstellungen und das Protokoll entfernt. Ist es deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die ePay.bg-Zahlungsdatensätze und der Bestellstatus ePay.bg payment on hold bleiben immer erhalten, sodass eine vor einer Neuinstallation gestartete Zahlung weiterhin bestätigt wird. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

ePay.bg ist eine Marke ihres jeweiligen Inhabers. Dieses Modul steht in keiner Verbindung zu ePay.bg und wird von ePay.bg weder unterstützt noch empfohlen.