VibeFox Helcim for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Ohne WooCommerce lässt sich das Plugin nicht aktivieren.

PHP: 8.0 oder neuer.

HTTPS und PCI DSS: Kartendaten werden an Ihrer Kasse eingegeben und von Ihrem Server über HTTPS an Helcim übertragen. Sie werden niemals 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 Rechten zur Transaktionsverarbeitung (siehe Konfiguration). Helcim verarbeitet CAD und USD. Ein Helcim-Testkonto (Entwicklerkonto) ist für Testzwecke optional verfügbar.

VibeFox-Lizenzschlüssel: Erhältlich auf vibefox.net. Ein Schlüssel gilt für eine Domain.

Installation

1. Gehen Sie in WordPress auf 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_helcim_gateway auch per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie in Helcim All Tools > Integrations > API Access Configuration, erstellen Sie einen API-Zugang mit Rechten zur Transaktionsverarbeitung (Käufe, Vorautorisierungen, Erfassungen, Erstattungen) und kopieren Sie dessen Token.

4. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > Helcim > Manage, oder klicken Sie auf der Seite „Plugins“ unter dem Namen des Plugins auf Settings.

5. Geben Sie Ihren VibeFox-Lizenzschlüssel in den Lizenzbereich oben auf der Seite ein und klicken Sie auf Activate.

6. Fügen Sie das Token in Live API token ein und das Token Ihres Helcim-Testkontos in Test API token, falls vorhanden.

7. Wählen Sie den Transaction type und die Account currencies, aktivieren Sie Enable / Disable und speichern Sie. Um zuerst zu testen, aktivieren Sie Test mode und zahlen Sie mit Ihrem Testkonto; schalten Sie ihn anschließend wieder aus.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Helcim. Über den Feldern warnt die Seite, wenn die Shopwährung nicht zu den Account currencies gehört und wenn bei aktivem Gateway das API-Token des aktuellen Modus fehlt. In beiden Fällen wird das Gateway an der Kasse ausgeblendet. In der Liste der Zahlungsmethoden wird das Gateway als einrichtungsbedürftig markiert, bis der aktuelle Modus über ein Token verfügt.

Enable / Disable: Enable Helcim Gateway aktiviert oder deaktiviert die Zahlungsmethode. Standard: aus.

Title: Der an der Kasse angezeigte Titel der Zahlungsmethode. Standard: Credit card (Helcim).

Description: Die an der Kasse angezeigte Beschreibung der Zahlungsmethode. 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. Vergeben Sie Rechte zur Transaktionsverarbeitung für Käufe, Vorautorisierungen, Erfassungen und Erstattungen. Helcim-Testkonten nutzen dieselbe API-Adresse wie Live-Konten, daher verwendet der Testmodus einfach das Token Ihres Helcim-Testkontos.

Live API token: Das API-Token Ihres Live-Helcim-Kontos. Wird verwendet, wenn der Testmodus ausgeschaltet ist.

Test mode: Use the Test API token (Helcim test account). Zahlungen, Erfassungen und Erstattungen gehen an Ihr Helcim-Testkonto, und Kunden sehen einen Hinweis auf den Testmodus. Erstattungen und Erfassungen einer Bestellung nutzen stets das Token des Modus, in dem die Bestellung bezahlt wurde. Standard: aus.

Test API token: Das API-Token Ihres Helcim-Testkontos (Entwicklerkontos). Wird verwendet, wenn der Testmodus eingeschaltet ist.

Zahlung

Transaction type: Wie die Karte belastet wird.

Purchase: Belastet die Karte sofort, und die Bestellung erhält den Status „In Bearbeitung“ (Standard).

Pre-authorization: Hält die Beträge nur zurück, und die Bestellung erhält den Status „In Wartestellung“. Erfassen Sie sie später über die Bestellaktion Capture Helcim pre-authorization, oder erstatten Sie die Bestellung vollständig, um die Reservierung aufzuheben.

Account currencies: Die Währungen, die Ihr Helcim-Konto verarbeiten kann. Bestellungen werden immer in der Bestellwährung abgerechnet. Für andere Währungen wird das Gateway an der Kasse ausgeblendet.

CAD — Canadian Dollar: Standard.

USD — US Dollar.

CAD and USD.

Erweitert

Debug log: Log API requests and responses unter WooCommerce > Status > Logs, Quelle wcp_helcim_gateway. Kartennummern werden auf die letzten 4 Ziffern gekürzt. CVC, Ablaufdatum, Token, Namen, Adressen, E-Mails und IP-Adressen werden niemals protokolliert. Standard: aus.

Delete data on uninstall: Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Credit card (Helcim)) und gibt an Ihrer Kasse Card Number, Expiry (MM/YY), CVC sowie Cardholder Name ein. Neben dem Titel werden Symbole für Visa, Mastercard, American Express und Discover angezeigt. Im Testmodus zeigt das Formular TEST MODE — payments go to a Helcim test account, no real charges are made. Vor dem Senden prüft das Plugin die Prüfsumme der Kartennummer, ob das Ablaufdatum gültig ist und nicht in der Vergangenheit liegt, dass der CVC aus 3 oder 4 Ziffern besteht und dass der Name ausgefüllt ist.

Beim Aufgeben der Bestellung sendet Ihr Server die Kartendaten als Kauf oder Vorautorisierung über den Gesamtbetrag in der Bestellwährung an Helcim. Rechnungsadresse, Telefonnummer und E-Mail-Adresse werden zur Adressprüfung übertragen. Die Zahlung erscheint in Helcim mit einer Rechnungsnummer aus Bestellnummer und Kurzcode. Helcim antwortet in derselben Anfrage. Die Bestellung wird erst als bezahlt markiert, wenn Helcim die Transaktion genehmigt hat und der genehmigte Betrag sowie die Währung mit der Bestellung übereinstimmen. Anschließend gelangt der Kunde auf die Seite „Bestellung erhalten“.

Es läuft immer nur ein Zahlungsversuch pro Bestellung gleichzeitig, und eine bereits bezahlte Bestellung wird nie erneut belastet. Jeder Versuch verwendet einen Idempotenzschlüssel. Antwortet Helcim nicht, verbleibt die Bestellung im Status „Zahlung ausstehend“, und ein erneuter Versuch innerhalb von 5 Minuten gibt das ursprüngliche Helcim-Ergebnis zurück, anstatt die Karte doppelt zu belasten.

Meldungen, die der Kunde 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 sonstigen abgewiesenen 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 abgewiesen wurde; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. bei doppelter Absendung. Technische Details werden in den Bestellnotizen und im Protokoll festgehalten.

Die Zahlungsmethode funktioniert an der klassischen Kasse, im Kassen-Block (mit denselben Kartenfeldern) und auf der Seite Pay for order. Sie ist kompatibel mit WooCommerce High-Performance Order Storage (HPOS).

Das Plugin verwendet weder HelcimPay.js noch Helcim.js, daher laufen die Kartendaten über Ihren Server. Es bietet keine gespeicherten Karten, Abonnements, ACH- oder Bankzahlungen, kein Apple Pay, Google Pay oder 3-D Secure und keine Helcim-Webhooks.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Die Zahlung wurde abgelehnt oder noch nicht bestätigt. Hat Helcim nicht geantwortet, fordert die Bestellnotiz dazu auf, die Helcim-Rechnung zu prüfen, bevor der Kunde erneut belastet wird.

Processing: Ein Kauf wurde genehmigt oder eine Vorautorisierung wurde erfasst. Bestellungen mit ausschließlich virtuellen herunterladbaren Produkten wechseln zu „Abgeschlossen“, dem WooCommerce-Standard. Die Bestellnotiz enthält Transaktions-ID, Genehmigungscode, Kartentyp, die letzten 4 Ziffern und den Modus. Die Transaktions-ID ist die Helcim-Transaktions-ID.

On hold (pre-authorization): Die Beträge sind nur zurückgehalten. Erfassen Sie sie über die Bestellaktion oder geben Sie sie durch eine vollständige Erstattung frei.

On hold after payment: Helcim hat eine Transaktion genehmigt, aber Betrag, Währung oder Transaktions-ID in der Antwort stimmen nicht mit der Bestellung überein. Die Notiz lautet Helcim response verification FAILED. Prüfen Sie die Transaktion in Helcim, bevor Sie die Bestellung ausführen.

Erfassung

Öffnen Sie die Bestellung (Status „In Wartestellung“), wählen Sie die Bestellaktion Capture Helcim pre-authorization und klicken Sie auf Update. Der aktuelle Gesamtbetrag der Bestellung abzüglich Erstattungen wird erfasst. Er darf niedriger sein als der autorisierte Betrag, aber nicht höher. Die Erfassung verwendet das Token des Modus, in dem die Bestellung bezahlt wurde. Nach erfolgreicher Erfassung wechselt die Bestellung zu „In Bearbeitung“, und die Transaktions-ID wird auf die Erfassungstransaktion geändert. Schlägt die Erfassung fehl, wird der Grund angezeigt und zu den Bestellnotizen hinzugefügt.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Credit card (Helcim) (die Schaltfläche zeigt Ihren Title). Vollständige und Teil-Erstattungen eines Kaufs oder einer erfassten Vorautorisierung werden unterstützt. Eine nicht erfasste Vorautorisierung kann nur vollständig erstattet werden: Die Reservierung wird freigegeben und dem Kunden wird nichts berechnet. Die Erstattung wird in dem Modus gesendet, in dem die Bestellung bezahlt wurde, daher muss das Token dieses Modus gesetzt sein. Sie zählt erst, wenn Helcim sie genehmigt. Lehnt Helcim sie ab, zeigt WooCommerce den Fehler an und es wird keine Erstattung verbucht. Eine erfolgreiche Erstattung wird den Bestellnotizen mit der Helcim-Erstattungstransaktions-ID hinzugefügt. Ein erneuter Versuch nach einer Zeitüberschreitung führt zu keiner doppelten Erstattung.

Das Plugin empfängt keine Helcim-Webhooks. Erfassungen, Erstattungen und Stornierungen im Helcim-Dashboard werden nicht in WooCommerce übernommen; führen Sie diese daher aus WooCommerce heraus aus.

Lizenzschlüssel

Das Plugin funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzbereich befindet sich ganz oben unter WooCommerce > Settings > Payments > Helcim. Fügen Sie den Schlüssel in License key ein und klicken Sie auf Activate. Der Bereich zeigt den Status, beispielsweise das Datum, bis zu dem die Lizenz aktiv ist, und Ihre Domain. Verwenden Sie Check now, um den Status erneut zu prüfen, Change key, um einen anderen Schlüssel einzugeben, und Remove key, um ihn von dieser Website zu entfernen. Der Link Manage licenses and domains in your account öffnet Ihr Konto auf vibefox.net.

Ein Schlüssel gilt für eine Domain. Das Entfernen des Schlüssels von einer Website gibt den Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Helcim den Kunden an der Kasse nicht angezeigt. Wird dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager sehen die Zahlungsmethode weiterhin, markiert als (unlicensed — visible to admins only), sodass Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Ein Hinweis erscheint auf der Seite „Plugins“ und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Erfassungen und Erstattungen funktionieren weiterhin.

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

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 Test API token im Testmodus) und die Warenkorbwährung eine der Account currencies ist. Auf der Seite Pay for order gilt die Bestellwährung. Die Einstellungsseite zeigt in beiden Fällen eine Warnung an.

Helcim hat nicht geantwortet und die Bestellung verbleibt im Status „Zahlung ausstehend“: Die Karte wurde möglicherweise belastet. Lesen Sie die Bestellnotiz und prüfen Sie die Rechnung in Helcim, bevor Sie den Kunden erneut belasten. Ein erneuter Versuch innerhalb von 5 Minuten liefert das ursprüngliche Ergebnis und belastet nicht doppelt.

Kunden sehen This payment method is temporarily unavailable: Das API-Token des aktuellen Modus ist leer oder wurde von Helcim abgewiesen. Laut Bestellnotiz sollten Token und Berechtigungen geprüft werden. Stellen Sie sicher, dass der API-Zugang über Rechte zur Transaktionsverarbeitung verfügt.

Zahlung mit einem Helcim-Grund fehlgeschlagen: Helcim hat die Anfrage abgelehnt, beispielsweise wegen der Karte oder der Rechnungsdaten. Die Bestellnotiz enthält die Einzelheiten.

Bestellung steht nach der Zahlung auf „In Wartestellung“: Lesen Sie die Bestellnotiz. Die Bestellung wurde vorautorisiert und wartet auf die Erfassung, oder die Antwort von Helcim stimmte nicht mit der Bestellung überein (Antwortüberprüfung fehlgeschlagen).

Erfassung ist nicht möglich: Der zu erfassende Betrag muss größer als 0 sein und darf den autorisierten Betrag nicht übersteigen, und das Token des Modus, in dem die Bestellung bezahlt wurde, muss hinterlegt sein.

Erstattung schlägt fehl: Lesen Sie die Meldung. Eine nicht erfasste Vorautorisierung kann nur vollständig erstattet werden. Eine Meldung zum Modus bedeutet, dass das Token des Modus, in dem die Bestellung bezahlt wurde, leer ist. Eine abgelehnte Erstattung wird nicht verbucht.

Testzahlungen: Der Testmodus sendet Zahlungen, Erfassungen und Erstattungen an Ihr Helcim-Testkonto. Bestellungen behalten den Modus, in dem sie bezahlt wurden; ein späterer Wechsel des Modus überträgt deren Erfassungen und Erstattungen nicht auf das andere Konto.

Der Lizenzbereich zeigt einen Fehler: Folgen Sie der Meldung im Bereich. Wenn der Schlüssel beispielsweise bereits auf einer anderen Domain verwendet wird, geben Sie einen Platz in Ihrem vibefox.net-Konto 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: Der Filter wc_hlg_supported_currencies ändert die Liste der Währungen, und wc_hlg_card_brands ändert die Kartensymbole an der Kasse.

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 dabei stets entfernt. Die Gateway-Einstellungen, die plugineigenen Optionen und die Protokolle werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestelldaten sind Teil der Bestellhistorie und werden niemals gelöscht. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Helcim ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist weder mit Helcim verbunden noch von Helcim empfohlen.