VibeFox Helcim 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 und PCI DSS: Kartendaten werden an der Kasse eingegeben und vom Server über HTTPS an Helcim gesendet. Sie werden nie gespeichert oder protokolliert, laufen aber über Ihren Server. Daher benötigt Ihr Shop ein SSL-Zertifikat, und Ihr Hosting muss PCI DSS (SAQ D) erfüllen.
Helcim-Konto: ein Helcim-Händlerkonto in Kanada oder den Vereinigten Staaten und ein API-Token mit Berechtigung zur Transaktionsabwicklung (siehe Konfiguration). Helcim verarbeitet CAD und USD. Ein Helcim-Testkonto (Entwicklerkonto) ist für Tests optional.
VibeFox-Lizenzschlüssel: Er wird auf vibefox.net gekauft. 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. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie VibeFox Helcim Gateway später in der Modulliste und klicken Sie dort 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. Öffnen Sie in Helcim All Tools > Integrations > API Access Configuration, erstellen Sie einen API-Zugang mit Berechtigung zur Transaktionsabwicklung (Zahlungen, Vorautorisierungen, Erfassungen, Erstattungen) und kopieren Sie dessen Token.
5. Fügen Sie das Token in Live API token ein, und das Token Ihres Helcim-Testkontos in Test API token, falls Sie eines haben.
6. Wählen Sie den Transaction type und die Account currencies, aktivieren Sie Enable / Disable und klicken Sie auf Save. Zum Testen aktivieren Sie zuerst Test mode und bezahlen mit Ihrem Testkonto. Danach deaktivieren Sie den Modus wieder.
Bei der Installation legt das Modul zwei Bestellstatus an, Helcim payment authorized und Helcim payment on hold. PrestaShop aktiviert ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen. Sie können dies unter Payment > Preferences einschränken.
Konfiguration
Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Helcim Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt Sie die Seite, wenn die Standardwährung Ihres Shops nicht zu den Account currencies gehört, und, solange die Zahlungsmethode aktiviert ist, wenn das API-Token des aktuellen Modus leer ist. In diesem Fall wird die Zahlungsmethode an der Kasse ausgeblendet.
Helcim
Enable / Disable: Enable Helcim Gateway schaltet die Zahlungsmethode ein oder aus. Standard: off.
Title: der Titel der Zahlungsmethode, der an der Kasse angezeigt wird. Er ist zugleich der Name der Zahlungsmethode, der in der Bestellung gespeichert wird. Standard: Credit card (Helcim). Pflichtfeld.
Description: die Beschreibung der Zahlungsmethode, die an der Kasse angezeigt wird. Standard: Pay securely with your credit card.
API-Zugangsdaten
Gehen Sie in Helcim zu All Tools > Integrations > API Access Configuration, erstellen Sie einen API-Zugang und kopieren Sie dessen Token. Geben Sie ihm die Berechtigung zur Transaktionsabwicklung für Zahlungen, Vorautorisierungen, Erfassungen und Erstattungen. Helcim-Testkonten verwenden dieselbe API-Adresse wie Live-Konten. Der Testmodus verwendet daher einfach das Token Ihres Helcim-Testkontos.
Live API token: das API-Token Ihres Live-Kontos bei Helcim. Es wird verwendet, wenn der Testmodus ausgeschaltet ist.
Test mode: verwendet das Test API token (Helcim-Testkonto). Zahlungen, Erfassungen und Erstattungen gehen an Ihr Helcim-Testkonto, und Kunden sehen einen Hinweis auf den Testmodus. Erfassungen und Erstattungen einer Bestellung verwenden immer das Token des Modus, in dem die Bestellung bezahlt wurde. Standard: off.
Test API token: das API-Token Ihres Helcim-Testkontos (Entwicklerkonto). Es wird verwendet, wenn der Testmodus eingeschaltet ist.
Gespeicherte Token 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 tokens: Setzen Sie einen Haken bei einem Token und klicken Sie auf Save, um es zu entfernen. Ein leeres Feld behält den gespeicherten Wert.
Zahlung
Transaction type: legt fest, wie die Karte belastet wird.
Account currencies: die Währungen, die Ihr Helcim-Konto verarbeiten kann. Bestellungen werden immer in der Warenkorbwährung belastet. Die Zahlungsmethode wird an der Kasse für andere Währungen ausgeblendet.
Erweitert
Debug log: schreibt API-Anfragen und -Antworten in logs/wc_hlg_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Kartennummern werden auf die letzten 4 Ziffern gekürzt. CVC, Ablaufdatum, Token, Namen, Adressen, E-Mail-Adressen und IP-Adressen werden nie protokolliert. Fehler (abgelehnte oder fehlgeschlagene Zahlungen, API-Fehler, fehlgeschlagene Erfassungen und Erstattungen) werden immer protokolliert, auch wenn diese Option ausgeschaltet ist. Standard: off.
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 die Option eingeschaltet, entfernt die Deinstallation des Moduls die Gateway-Einstellungen und seine Protokolldateien. Die Helcim-Transaktionen, Erstattungen und Bestellstatus bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation weiterhin erfasst und erstattet werden können. Standard: off.
Kasse
Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Credit card (Helcim), mit einem Kartensymbol) und gibt im Formular darunter Card Number, Expiry (MM/YY), CVC und Cardholder Name ein. Im Testmodus zeigt das Formular TEST MODE — payments go to a Helcim test account, no real charges are made. Wenn der Kunde die Bestellung abschickt, prüft das Modul die Prüfsumme der Kartennummer, ob das Ablaufdatum gültig und nicht in der Vergangenheit ist, ob der CVC 3 oder 4 Ziffern hat und ob der Name ausgefüllt ist. Fehler werden an der Kasse angezeigt, und es wird nichts an Helcim gesendet.
Ihr Server sendet die Karte dann an Helcim, als Kauf oder Vorautorisierung über die Warenkorbsumme in der Warenkorbwährung. Rechnungsadresse, Telefonnummer und E-Mail-Adresse werden zur Adressprüfung übermittelt. Die Zahlung erscheint bei Helcim mit einer Rechnungsnummer, die aus der Warenkorbnummer, -PS und einem kurzen Code besteht. Helcim antwortet in derselben Anfrage. Die Bestellung wird erst angelegt, nachdem Helcim die Transaktion genehmigt hat, und der Kunde landet auf der üblichen Bestellbestätigungsseite. Vorher existiert keine Bestellung.
Pro Warenkorb läuft jeweils nur ein Zahlungsversuch, und ein Warenkorb mit bereits vorhandener Bestellung wird nie erneut belastet. Jeder Versuch verwendet einen Idempotenzschlüssel. Antwortet Helcim nicht, wird keine Bestellung angelegt. Ein erneuter Versuch innerhalb von 5 Minuten gibt das ursprüngliche Helcim-Ergebnis zurück, anstatt die Karte zweimal zu belasten. Wurde die Zahlung genehmigt, aber die Bestellung konnte nicht angelegt werden, legt der nächste Versuch desselben Warenkorbs die Bestellung an, ohne die Karte erneut zu belasten.
Meldungen, die der Kunde an der Kasse sehen kann: Your card was declined. Please check the card details or use another card., wenn Helcim ablehnt; Payment failed: mit dem Grund von Helcim bei anderen abgelehnten Anfragen; We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card., wenn Helcim nicht antwortet; This payment method is temporarily unavailable. Please choose another payment method., wenn das API-Token fehlt oder von Helcim abgelehnt wird; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. bei einer doppelten Übermittlung; Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again., wenn die Zahlung genehmigt wurde, die Bestellung aber nicht angelegt werden konnte. Der Warenkorb bleibt erhalten. Technische Details gehen in das Protokoll.
Das Modul verwendet weder HelcimPay.js noch Helcim.js, daher laufen Kartendaten über Ihren Server. Es gibt keine gespeicherten Karten, Abonnements, ACH- oder Banküberweisungen, kein Apple Pay, Google Pay oder 3-D Secure und keine Helcim-Webhooks.
Bestellungen und Erstattungen
Bestellstatus
No order: Die Karte wurde abgelehnt, Helcim hat nicht geantwortet oder der Kunde hat noch nicht bezahlt. Es existiert nur der Warenkorb. Ablehnungen und Fehler werden im Protokoll festgehalten.
Payment accepted: Ein Kauf wurde genehmigt oder eine Vorautorisierung wurde erfasst. Die Zahlung wird mit der Transaktions-ID von Helcim gespeichert, und eine Notiz zeigt Transaktions-ID, Genehmigungscode, Kartentyp, die letzten 4 Ziffern und den Modus.
Helcim payment authorized: Eine Vorautorisierung wurde genehmigt. Die Beträge sind nur reserviert. Erfassen oder geben Sie sie mit einer vollständigen Erstattung frei.
Helcim payment on hold: Helcim hat eine Transaktion genehmigt, aber Betrag, Währung oder Transaktions-ID in der Antwort stimmen nicht mit dem Warenkorb überein, zum Beispiel nach einer Teilgenehmigung oder wenn sich der Warenkorb während der Zahlung geändert hat. Die Notiz lautet Helcim response verification FAILED. Bei einem Kauf wird die Zahlung mit dem Betrag gespeichert, den Helcim tatsächlich belastet hat. Prüfen Sie die Transaktion bei Helcim, bevor Sie die Bestellung ausliefern.
Refunded: Die Zahlung wurde über das Modul vollständig erstattet.
Canceled: Eine nicht erfasste Vorautorisierung wurde freigegeben. Der Kunde wurde nicht belastet.
Wird für einen Warenkorb, der bereits eine Bestellung hat, eine zweite Transaktion genehmigt, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, sie zu prüfen und bei Helcim zu stornieren oder zu erstatten.
Helcim-Zahlungsblock
Die Bestellseite zeigt einen Block Helcim payment mit der Transaktions-ID (und nach einer Erfassung der Vorautorisierungs-ID), dem Transaktionstyp und dem Erfassungsstatus, der Rechnungsnummer, der Karte und dem Genehmigungscode, dem genehmigten Betrag, der Bestellsumme und dem erstatteten Betrag, einem Abzeichen Test mode für Testzahlungen, dem Erstattungsverlauf und den Helcim notes der Bestellung. Für Erfassung und Erstattungen benötigen Sie das Recht, Bestellungen zu bearbeiten.
Erfassung
Klicken Sie bei einer Bestellung im Status Helcim payment authorized im Block auf Capture payment und bestätigen Sie Capture the pre-authorized amount through Helcim? Erfasst wird die aktuelle Bestellsumme abzüglich der Erstattungen. Sie kann niedriger sein als der vorautorisierte Betrag, aber nicht höher. Die Erfassung verwendet das Token des Modus, in dem die Bestellung bezahlt wurde. Nach einer erfolgreichen Erfassung wird die Bestellung auf Zahlung akzeptiert gesetzt, und die Zahlung wird mit der Transaktions-ID der Erfassung gespeichert. Schlägt die Erfassung fehl, zeigt der Block den Grund an und ergänzt ihn um die Notizen.
Erstattungen
Geben Sie im Block den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Helcim. Bestätigen Sie Refund this amount through Helcim? This cannot be undone. Vollständige und Teilerstattungen einer Zahlung oder einer erfassten Vorautorisierung werden unterstützt, bis zu dem Betrag, den Helcim tatsächlich belastet hat. Nach einer Teilgenehmigung können Sie daher nicht mehr erstatten, als der Kunde bezahlt hat. Bei einer nicht erfassten Vorautorisierung lautet die Schaltfläche Release pre-authorization: Freigegeben werden kann nur der volle Betrag, die Reservierung wird entfernt und die Bestellung wird auf Storniert gesetzt.
Die Erstattung wird im Modus gesendet, in dem die Bestellung bezahlt wurde, daher muss dessen Token gesetzt sein. Sie zählt nur, wenn Helcim sie genehmigt. Lehnt Helcim sie ab, zeigt der Block den Fehler an, und es wird keine Erstattung erfasst. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen mit der Helcim-Transaktions-ID der Erstattung hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine Teilerstattung ändert den Status nicht. Ein erneuter Versuch nach einer Zeitüberschreitung erstattet nicht doppelt.
Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Helcim zurück. Das Modul empfängt keine Helcim-Webhooks: Erfassungen, Erstattungen und Stornierungen im Helcim-Dashboard werden nicht in PrestaShop übernommen. Führen Sie sie daher über die Bestellseite aus.
Lizenzschlüssel
Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Helcim Gateway ist der erste Block auf Modules > Module Manager > VibeFox Helcim Gateway > 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, 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-helcim 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. Nach einer Änderung der Shop-Adresse oder nachdem Sie in Ihrem 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 für eine Domain: die 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 Helcim an der Kasse 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 wird die Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul einrichten, bevor Sie einen Schlüssel kaufen, es an der Kasse aber nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: bereits erfolgte Zahlungen bleiben erhalten, und Erfassungen und Erstattungen funktionieren weiter.
Wenn eine Lizenz abläuft, 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. Ein Cron-Job ist nicht nötig. Beim Deinstallieren oder Zurücksetzen des Moduls werden immer der Lizenzschlüssel und der Lizenzstatus entfernt.
Fehlerbehebung
Helcim erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist, der aktuelle Modus sein API-Token hat (Live API token oder im Testmodus Test API token) und die Warenkorbwährung zu den Account currencies gehört. Die Einstellungsseite zeigt eine Warnung, wenn das Token fehlt oder die Shop-Währung nicht erlaubt ist. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist.
Der Kunde sah „We could not confirm your payment“: Helcim hat nicht geantwortet, daher könnte die Karte belastet worden sein. Schauen Sie im Feld Log nach: Der Fehler nennt den Warenkorb und die Helcim-Rechnung. Prüfen Sie diese Rechnung bei Helcim, bevor Sie den Kunden erneut belasten. Ein erneuter Versuch innerhalb von 5 Minuten gibt das ursprüngliche Ergebnis zurück und belastet nicht doppelt.
Kunden sehen „This payment method is temporarily unavailable“: Das API-Token des aktuellen Modus ist leer oder wurde von Helcim abgelehnt. Das Protokoll fordert auf, das Token und seine Berechtigungen zu prüfen. Stellen Sie sicher, dass der API-Zugang die Berechtigung zur Transaktionsabwicklung hat.
Zahlung fehlgeschlagen mit einem Grund von Helcim: Helcim hat die Anfrage abgelehnt, zum Beispiel wegen der Karte oder der Rechnungsdaten. Die Details stehen im Protokoll.
Der Kunde sah „Your payment was received, but the order could not be completed“: Helcim hat die Zahlung genehmigt, aber PrestaShop konnte die Bestellung nicht anlegen (zum Beispiel, weil das Modul deaktiviert war). Das Protokoll nennt den Grund. Wenn der Kunde denselben Warenkorb erneut absendet, wird die Bestellung aus der genehmigten Zahlung angelegt, ohne eine zweite Belastung.
Bestellung im Status Helcim payment on hold: Lesen Sie die Notizen im Helcim-Block. Die Antwort von Helcim stimmte nicht mit dem Warenkorb überein (Prüfung der Antwort fehlgeschlagen). Prüfen Sie die Transaktion bei Helcim und liefern Sie danach die Bestellung aus oder erstatten Sie die Zahlung.
Erfassung nicht möglich: Der zu erfassende Betrag muss größer als 0 und darf nicht höher als der vorautorisierte Betrag sein, und das Token des Modus, in dem die Bestellung bezahlt wurde, muss gesetzt sein.
Erstattung schlägt fehl: Lesen Sie die Meldung. Eine nicht erfasste Vorautorisierung kann nur vollständig freigegeben werden. Eine Meldung zum Modus bedeutet, dass das Token des Modus, in dem die Bestellung bezahlt wurde, leer ist. Eine abgelehnte Erstattung wird nicht erfasst.
Testzahlungen: Der Testmodus sendet Zahlungen, Erfassungen und Erstattungen an Ihr Helcim-Testkonto. Bestellungen behalten den Modus, in dem sie bezahlt wurden. Ein späterer Moduswechsel verschiebt ihre Erfassungen und Erstattungen daher nicht auf das andere Konto.
Deinstallation
Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Helcim 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 Gateway-Einstellungen und das Protokoll entfernt. Ist die Option ausgeschaltet, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Helcim-Transaktionen und Erstattungen sowie die Bestellstatus Helcim payment authorized und Helcim payment on hold bleiben immer erhalten, sodass zuvor bezahlte Bestellungen nach einer Neuinstallation weiterhin erfasst und erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.
Helcim ist eine Marke des jeweiligen Inhabers. Dieses Modul ist nicht mit Helcim verbunden und wird nicht von Helcim unterstützt.