VibeFox ECPay 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: Neuer Taiwan-Dollar (TWD). ECPay rechnet nur in TWD ab, daher wird die Zahlungsart nur angezeigt, wenn der Warenkorb des Kunden in TWD ist. Fügen Sie TWD unter International > Localization > Currencies hinzu, falls Ihr Shop es nicht hat. Beträge werden in ganzen TWD übermittelt, da ECPay keine Dezimalstellen akzeptiert: Warenkorbsummen werden auf den nächsten Dollar gerundet. Verwenden Sie für TWD-Preise 0 Nachkommastellen, um Rundungen zu vermeiden.
ECPay-Konto: Für Live-Zahlungen benötigen Sie MerchantID, HashKey und HashIV Ihres ECPay-Händlerkontos aus dem ECPay-Händler-Backoffice (vendor.ecpay.com.tw). Zum Testen ist kein ECPay-Konto nötig.
Erreichbarkeit des Shops: Ihr Shop muss aus dem Internet über HTTP/HTTPS auf Port 80/443 erreichbar sein, damit ECPay Zahlungsbenachrichtigungen zustellen kann. Eine Firewall oder eine Basis-Authentifizierung vor dem Shop blockiert sie.
VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. Ein Schlüssel funktioniert für eine Domain.
Installation
1. Gehen Sie im Backoffice 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 ECPay Payment 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. Aktivieren Sie Enable/Disable, wählen Sie die Zahlungsmethoden und lassen Sie Test Mode für Ihre ersten Tests eingeschaltet. Klicken Sie auf Save.
5. Für Live-Zahlungen tragen Sie die Merchant ID, den Hash Key und die Hash IV ein (siehe Konfiguration), schalten Test Mode aus und klicken Sie auf Save.
Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting ECPay payment und ECPay 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; TWD muss für das Modul erlaubt bleiben.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite einen Fehler, wenn Ihr Shop keine TWD-Währung hat (dann wird ECPay nicht an der Kasse angezeigt), oder eine Warnung, wenn die Standardwährung nicht TWD ist (dann wird ECPay nur Kunden angezeigt, die in TWD bezahlen). Sie zeigt einen Fehler, wenn der Livebetrieb keine MerchantID, keinen HashKey und keine HashIV hat. Solange der Testmodus eingeschaltet ist, warnt sie davor, dass Zahlungen an die ECPay-Sandbox mit dem öffentlichen Testhändler 3002607 gehen, dass kein Geld eingezogen wird und dass jeder, der die öffentlichen Sandbox-Schlüssel kennt, Testbestellungen bestätigen könnte. Deshalb muss der Testmodus ausgeschaltet sein, bevor Sie echte Bestellungen annehmen.
ECPay (綠界)
Enable/Disable: Enable ECPay Payment schaltet die Zahlungsmethode ein oder aus. Standard: aus.
Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Er wird auch als Name der Zahlungsmethode in der Bestellung gespeichert. Standard: ECPay (綠界). Pflichtfeld: Die Seite lässt sich nicht mit leerem Titel speichern.
Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).
ECPay-Konto
Ihre MerchantID, Ihren HashKey und Ihre HashIV finden Sie im ECPay-Händler-Backoffice (vendor.ecpay.com.tw) unter System development management > System integration settings (系統開發管理 > 系統介接設定).
Test Mode: Sendet Zahlungen an die ECPay-Sandbox (payment-stage.ecpay.com.tw) mit dem öffentlichen ECPay-Testhändler 3002607. Kein echtes Geld. Die unten stehenden Zugangsdaten werden nur verwendet, wenn der Testmodus ausgeschaltet ist. Standard: eingeschaltet. Solange er eingeschaltet ist, sehen Kunden unter der Zahlungsmethode TEST MODE — ECPay sandbox, no real money is charged.
Merchant ID: Ihre ECPay-Merchant-ID (Produktion). Wird im Testmodus ignoriert.
Hash Key: Ihr ECPay-Hash-Key (Produktion). Wird im Testmodus ignoriert.
Hash IV: Ihre ECPay-Hash-IV (Produktion). Wird im Testmodus ignoriert.
Leerzeichen und Zeilenumbrüche in eingefügten Zugangsdaten machen jede Signatur ungültig; sie werden deshalb beim Speichern entfernt, und die Seite weist Sie darauf hin. Ein gespeicherter Hash Key und eine gespeicherte Hash IV werden nie erneut 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: Setzen Sie ein Häkchen bei Hash Key oder Hash IV und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Zahlungsoptionen
Enabled Payment Methods: Die Methoden, die Kunden angeboten werden. Bei mehr als einer wählt der Kunde an der Kasse. Bestellungen per ATM, CVS und Barcode bleiben in Awaiting ECPay payment, bis der Kunde bezahlt. Es muss mindestens eine Methode ausgewählt sein; ist keine ausgewählt, wird Credit Card aktiviert und die Seite weist Sie darauf hin. Standard: Credit Card.
Default Payment Method: Die vorausgewählte Methode. Sie muss eine der aktivierten Methoden sein; andernfalls wird die erste aktivierte Methode verwendet. Standard: Credit Card.
Order Prefix: Das Präfix der ECPay-Transaktionsnummer (MerchantTradeNo), bis zu 5 Buchstaben oder Ziffern. Andere Zeichen werden beim Speichern mit einem Hinweis entfernt. Nützlich, wenn mehrere Shops ein ECPay-Konto teilen: Geben Sie jedem Shop ein eigenes Präfix. Standard: EC.
Zahlungsbenachrichtigungen
ECPay sendet Zahlungsergebnisse an Ihren Shop. Dieser Abschnitt zeigt die Notification URL. Mit SEO-freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_ecpay_payment_gateway/notify, möglicherweise mit einem Sprachcode wie /en/. Die URL wird bei jeder Zahlung übermittelt, daher müssen Sie bei ECPay nichts einrichten. Sie muss aber aus dem Internet über Port 80/443 erreichbar sein, ohne Firewall oder Basis-Authentifizierung davor. Der Wartungsmodus und die Ländereinschränkung Ihres Shops blockieren sie nicht.
Jede Benachrichtigung wird anhand ihrer CheckMacValue-Signatur mit den Schlüsseln der Umgebung (Test oder Live) geprüft, in der die Zahlung gestartet wurde, sowie anhand der MerchantID dieser Zahlung. Benachrichtigungen ohne gültige Signatur werden abgelehnt, und ECPay sendet sie erneut. Ohne die Benachrichtigung wird keine Bestellung angelegt; prüfen Sie die Zahlung im ECPay-Backoffice.
Erweitert
Enable Logging: Schreibt Bestell-IDs, Transaktionsnummern, Beträge und ECPay-Rückgabecodes in logs/ecpay_p_debug.log.php im Modulordner. Die Datei lässt sich über das Web nicht öffnen. Schlüssel oder Kundendaten werden nicht protokolliert. Fehler werden immer protokolliert, auch wenn dieser Schalter aus ist. Standard: aus.
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 dies eingeschaltet, entfernt die Deinstallation des Moduls seine Einstellungen und das Protokoll. Die ECPay-Zahlungsdatensätze und die Bestellstatus bleiben immer erhalten, damit bestehende Bestellungen nach einer Neuinstallation weiter funktionieren. Standard: aus.
Kasse
Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig ECPay (綠界)). Sind mehrere Methoden aktiviert, wählt der Kunde außerdem unter Payment Method Credit Card, ATM (Virtual Account), CVS (Convenience Store) oder Barcode.
Nach der Bestätigung sieht der Kunde Redirecting to ECPay for payment. Please wait... und wird auf die ECPay-Zahlungsseite weitergeleitet, mit einer Schaltfläche Proceed to ECPay, falls die Weiterleitung nicht startet. Die Warenkorbsumme wird in ganzen TWD mit den Namen und Mengen der Produkte übermittelt. Die ECPay-Seite öffnet sich auf Traditionellem Chinesisch für taiwanesische und Hongkonger Sprachen, auf Vereinfachtem Chinesisch, Koreanisch oder Japanisch für diese Sprachen und auf Englisch für alle anderen. Dabei folgt sie der Shop-Sprache des Kunden. Zu diesem Zeitpunkt existiert noch keine Bestellung.
Die Bestellung wird erst angelegt, nachdem ECPay sie mit einer signierten Server-Benachrichtigung bestätigt hat. Klickt der Kunde auf der ECPay-Seite auf den Link zurück zum Shop und existiert die Bestellung bereits, öffnet sich die Standard-Bestellbestätigungsseite. Sie zeigt Your ECPay payment has been received. bei einer bezahlten Bestellung, Your ECPay payment was received and is being reviewed by the store. bei einer Bestellung in Prüfung und die Zahlungsanweisungen bei einer ausstehenden ATM-, CVS- oder Barcode-Bestellung. Ist die Benachrichtigung noch nicht eingetroffen, zeigt eine Seite Payment confirmation We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment. mit den Schaltflächen Check again und Back to checkout. Hat ECPay gemeldet, dass die Zahlung fehlgeschlagen ist, kehrt der Kunde zur Kasse zurück, mit The payment was not completed. You can try again or choose another payment method. Der Warenkorb bleibt erhalten.
Bei ATM, CVS und Barcode erhält der Kunde zuerst die Zahlungsdaten. Die Bestellung wird in Awaiting ECPay payment angelegt. Die Bankleitzahl und das virtuelle Konto, der Zahlungscode des Convenience-Stores oder die Barcodes, der Betrag und das Datum Pay before werden unter ECPay payment instructions auf der Bestellbestätigungsseite und in den Bestelldetails des Kunden angezeigt. Wenn der Kunde bezahlt, sendet ECPay eine weitere Benachrichtigung und die Bestellung wird als bezahlt markiert. Zahlungsanweisungen werden nicht in PrestaShop-E-Mails aufgenommen.
Jeder Versuch erzeugt eine neue ECPay-Transaktionsnummer, weil ECPay wiederverwendete Nummern ablehnt. Wiederholungen nach einer fehlgeschlagenen Zahlung funktionieren daher, und kehrt der Kunde im Browser zur Weiterleitungsseite zurück, wird ein neuer Versuch gestartet. Ein Warenkorb kann bis zu 30 Zahlungsversuche haben. Sobald der Warenkorb eine Bestellung hat, kann er über die Kasse nicht erneut bezahlt werden; eine ausstehende ATM- oder CVS-Bestellung wird mit den bereits ausgegebenen Daten bezahlt.
Kann die Zahlung nicht gestartet werden, bleibt der Kunde an der Kasse mit einer kurzen Meldung, zum Beispiel The order total is too small for ECPay. wenn die Summe nach der Rundung unter 1 TWD liegt. Die eigenen Betragsgrenzen von ECPay je Methode werden auf der ECPay-Seite geprüft, nicht an der Kasse.
Das Modul nimmt Einmalzahlungen nur auf der ECPay-Seite an. Es bietet keine Erstattungen aus PrestaShop, keine gespeicherten Karten, keine Abonnements oder wiederkehrenden Zahlungen (定期定額), keine Ratenzahlungen, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, E-Rechnungen oder Logistik und keine serverseitige Statusabfrage. Kann Ihr Shop die Benachrichtigung nicht empfangen, prüfen Sie die Zahlung im ECPay-Backoffice.
Bestellungen
Bestellstatus
No order yet: Der Kunde wurde zu ECPay geschickt und hat nicht bezahlt, oder die Benachrichtigung ist noch nicht eingetroffen. Es existiert nur der Warenkorb.
Awaiting ECPay payment: Der Kunde hat ATM, CVS oder Barcode gewählt und die Zahlungsdaten erhalten. Die Notiz zeigt die Bankleitzahl und das virtuelle Konto, den Zahlungscode oder die Barcodes und die Frist.
Payment accepted: Die Zahlung wurde bestätigt. Sie wird mit der ECPay-TradeNo als Transaktions-ID erfasst, und eine Notiz zeigt die TradeNo, die Zahlungsart, den Betrag und die Transaktionsnummer (bei Sandbox-Zahlungen mit einer Markierung für den Testmodus).
ECPay payment on hold: ECPay hat einen anderen Betrag oder eine andere Währung gemeldet als im Warenkorb (zum Beispiel wurde der Warenkorb in einem anderen Tab geändert, nachdem die Zahlung gestartet wurde), eine Sandbox-Zahlung ist eingegangen, nachdem Sie in den Livebetrieb gewechselt haben (es wurde kein echtes Geld eingezogen), oder die Zahlung ist eingegangen, nachdem die Bestellung storniert war (dann wird die Zahlung erfasst). Die Notiz erklärt es. Vergleichen Sie mit dem ECPay-Backoffice und bearbeiten Sie die Bestellung oder erstatten Sie die Zahlung dort.
Payment error: ECPay hat gemeldet, dass die letzte ATM-, CVS- oder Barcode-Zahlung einer ausstehenden Bestellung fehlgeschlagen ist. Die Notiz zeigt den ECPay-Rückgabecode und die Meldung.
Wiederholte Benachrichtigungen werden ignoriert. Eine bezahlte, erstattete oder stornierte Bestellung wird durch einen späten Fehler nie wieder geöffnet. Eine zweite Zahlung für eine bereits bezahlte Bestellung, zum Beispiel aus zwei Browser-Tabs, wird einmal als Notiz vermerkt, damit Sie sie im ECPay-Backoffice erstatten können. Simulierte Zahlungen, die aus dem ECPay-Backoffice gestartet werden, werden nur vermerkt und markieren eine Bestellung nie als bezahlt, weil ECPay dafür kein Geld einzieht.
ECPay-Zahlungsblock
Die Bestellseite zeigt einen Block ECPay payment mit jedem Zahlungsversuch der Bestellung: die MerchantTradeNo mit einem Kennzeichen Test mode für Sandbox-Versuche, die Methode, den Betrag in TWD, den Status, die ECPay-TradeNo, die Zahlungsart und das Datum sowie den ECPay-Rückgabecode. Darunter stehen die ECPay notes der Bestellung. Bei einer Bestellung im Status ECPay payment on hold erinnert Sie der Block daran, sie mit dem ECPay-Backoffice abzugleichen.
Erstattungen
Erstattungen aus PrestaShop sind nicht verfügbar. Erstatten Sie die Zahlung im ECPay-Backoffice und aktualisieren Sie danach die Bestellung in PrestaShop manuell. Die standardmäßigen PrestaShop-Erstattungsschaltflächen auf der Bestellseite senden über ECPay kein Geld zurück.
Lizenzschlüssel
Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox ECPay Payment Gateway ist der erste Block auf Modules > Module Manager > VibeFox ECPay 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 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-ecpay 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 ECPay 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
ECPay wird an der Kasse nicht angezeigt: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, der Warenkorb des Kunden in TWD ist und im Livebetrieb Merchant ID, Hash Key und Hash IV gesetzt sind. Die Einstellungsseite zeigt in jedem dieser Fälle eine Meldung. Prüfen Sie unter Payment > Preferences, ob das Modul für TWD, das Land des Kunden und die Kundengruppe des Kunden erlaubt ist.
Die Zahlung ist durchgegangen, aber es wurde keine Bestellung angelegt: Die ECPay-Benachrichtigung hat Ihren Shop nicht erreicht (Shop nicht erreichbar, Firewall, Basis-Authentifizierung). ECPay wiederholt den Versand mehrfach. Sie können die Transaktion auch im ECPay-Backoffice prüfen. Schalten Sie Enable Logging ein, um die vom Modul empfangenen Benachrichtigungen zu sehen; abgelehnte Benachrichtigungen werden in jedem Fall als Fehler protokolliert.
Benachrichtigung antwortet 0|CheckMacValue verification failed: Der Hash Key oder die Hash IV passt nicht zu Ihrem ECPay-Konto, oder die Zahlung wurde in der anderen Umgebung gestartet. Kopieren Sie sie erneut aus dem ECPay-Backoffice.
Benachrichtigung antwortet 0|MerchantID mismatch: Die Benachrichtigung gehört zu einem anderen ECPay-Händler als dem, mit dem die Zahlung gestartet wurde.
Benachrichtigung antwortet 0|Order not found: Die Transaktionsnummer wurde nicht von diesem Shop ausgestellt, zum Beispiel wenn mehrere Shops ein ECPay-Konto teilen. Geben Sie jedem Shop eine eigene Order Prefix.
Benachrichtigung antwortet 0|Retry: Der Warenkorb wurde im selben Moment von einer anderen Benachrichtigung verarbeitet, oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). ECPay sendet die Benachrichtigung erneut. Schalten Sie Enable Logging ein, um den Grund zu sehen.
Die Benachrichtigungs-URL zeigt 0|Method not allowed in the browser: Das ist normal. Die URL akzeptiert nur Anfragen von ECPay.
Der Kunde sieht „The order total is too small for ECPay.“: Die Warenkorbsumme liegt nach der Rundung unter 1 TWD und kann nicht mit ECPay bezahlt werden.
Der Kunde sieht „Too many payment attempts for this order“: Der Warenkorb hat 30 Zahlungsversuche erreicht. Bitten Sie den Kunden, einen neuen Warenkorb zu starten.
Die Bestellung ist ECPay payment on hold: Lesen Sie die Notizen im Block ECPay payment (siehe Bestellstatus), vergleichen Sie sie mit dem ECPay-Backoffice und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung dort.
Entwickler: Der Hook actionEcpayPRequestParams erlaubt einem anderen Modul, die an ECPay gesendeten Parameter zu ändern; Händler, Transaktionsnummer und Betrag können damit nicht geändert werden.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox ECPay Payment Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete Data on Uninstall eingeschaltet, werden die Einstellungen und das Protokoll entfernt. Ist es ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die ECPay-Zahlungsdatensätze und die Bestellstatus Awaiting ECPay payment und ECPay payment on hold bleiben immer erhalten, damit späte Benachrichtigungen zu alten Zahlungen auch nach einer Neuinstallation geprüft werden. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
ECPay ist eine Marke ihres jeweiligen Inhabers. Dieses Modul steht in keiner Verbindung zu ECPay und wird von ECPay nicht unterstützt.