VibeFox Pin Payments 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.

Pin-Payments-Konto: ein Pin-Payments-Händlerkonto (für Unternehmen in Australien oder Neuseeland; Kunden können von überall aus bezahlen). Sie benötigen dessen Publishable Key und Secret Key, für den Live-Betrieb und für Tests die Testumgebung. Ein Webhook-Secret wird nicht benötigt: Das Modul verwendet keine Webhooks. Kartendaten werden vom Browser des Kunden direkt über Pin.js an Pin Payments gesendet und erreichen Ihren Shop nie, daher fällt der Shop unter PCI SAQ A-EP.

VibeFox-Lizenzschlüssel: Kauf über vibefox.net. Ein Schlüssel gilt 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 aus.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später in der Modulliste nach VibeFox Pin Payments Gateway und klicken Sie auf Configure.

3. Fügen 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 im Pin-Payments-Dashboard Account > API Keys und kopieren Sie Ihre Testschlüssel in Test publishable key und Test secret key. Lassen Sie Test mode eingeschaltet, aktivieren Sie Enable/Disable und klicken Sie auf Save.

5. Legen Sie eine Testbestellung mit einer Pin-Payments-Testkarte an. Wenn alles funktioniert, geben Sie die Live-Schlüssel ein, schalten Test mode aus und speichern Sie.

Bei der Installation legt das Modul den Bestellstatus Pin Payments payment on hold an. PrestaShop bietet ein neues Zahlungsmodul für die Währungen, Kundengruppen und Länder an, die zum Zeitpunkt der Installation aktiv sind. Sie können das unter Payment > Preferences ändern; später aktivierte Länder müssen dort angehakt werden.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Pin Payments Gateway > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite eine Warnung, solange der Testmodus aktiv ist, einen Fehler, solange der Publishable Key oder der Secret Key des aktuellen Modus leer ist, und einen Fehler, wenn Pin Payments die Standardwährung des Shops nicht unterstützt (mit der Liste der unterstützten Währungen). Ohne beide Schlüssel des aktuellen Modus wird die Zahlungsart auf der Kasse ausgeblendet. Ein leerer Title wird nicht gespeichert: Die Seite zeigt Enter a title for the payment method.

Pin Payments

Enable/Disable: Enable Pin Payments schaltet die Zahlungsart ein oder aus. Standard: aus.

Title: der Name der Zahlungsart, den Kunden auf der Kasse sehen. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Credit card (Pin Payments). Pflichtfeld.

Description: der Text, der unter der Zahlungsart auf der Kasse angezeigt wird. Standard: Pay with your credit card via Pin Payments.

API-Schlüssel

Ihre Schlüssel finden Sie im Pin-Payments-Dashboard unter Account > API Keys. Testschlüssel funktionieren nur mit der Test-API, Live-Schlüssel nur mit der Live-API. Der Publishable Key wird von Pin.js im Browser des Kunden verwendet. Der Secret Key verlässt Ihren Server nie.

Test mode: verwendet die Testumgebung von Pin Payments (test-api.pinpayments.com) und die Testschlüssel. Es werden keine echten Belastungen durchgeführt, und Kunden sehen TEST MODE — no real charges will be made. unter der Zahlungsart. Ist er ausgeschaltet, werden die Live-API und die Live-Schlüssel verwendet. Standard: ein.

Test publishable key: der Publishable Key Ihres Pin-Payments-Testkontos.

Test secret key: der Secret Key Ihres Pin-Payments-Testkontos.

Live publishable key: der Publishable Key Ihres Live-Kontos bei Pin Payments.

Live secret key: der Secret Key Ihres Live-Kontos bei Pin Payments.

Leerzeichen um die Schlüssel werden entfernt. Gespeicherte geheime Schlüssel 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 secrets: Haken Sie einen geheimen Schlüssel an und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert bei.

Erweitert

Debug log: schreibt in logs/wc_ppg_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler werden immer protokolliert; aktivieren Sie diese Option, um außerdem jeden API-Aufruf zu protokollieren. Kartendaten, API-Schlüssel und personenbezogene Kundendaten werden nie protokolliert. 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 die Option aktiv, entfernt das Deinstallieren des Moduls die Gateway-Einstellungen und das Protokoll. Die Zahlungsdaten der Bestellungen (Belastungen und Erstattungen) und der Bestellstatus Pin Payments payment on hold bleiben immer erhalten. Standard: aus.

Kasse

Die Zahlungsart wird angezeigt, wenn sie aktiviert ist, beide Schlüssel des aktuellen Modus gesetzt sind, die Warenkorbwährung eine der 14 unterstützten Währungen ist (AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR) und das Modul für den Warenkorb unter Payment > Preferences erlaubt ist.

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Credit card (Pin Payments), mit den Symbolen für Visa, Mastercard und American Express) und füllt Card number, Expiry (MM / YY), CVC und Name on card aus. Vor dem Absenden prüft das Formular die Länge der Kartennummer, den Ablaufmonat und das Ablaufjahr, einen CVC mit 3 oder 4 Ziffern und den Namen.

Wenn der Kunde die Bestellung absendet, überträgt Pin.js die Kartendaten und die Rechnungsadresse des Warenkorbs direkt aus dem Browser an Pin Payments und erhält ein einmalig verwendbares Kartentoken. Nur dieses Token wird an Ihren Shop gesendet. Das Modul erstellt dann eine erfasste Belastung über den Gesamtbetrag des Warenkorbs in der Warenkorbwährung, mit der E-Mail-Adresse des Kunden und der Beschreibung <shop name> - Cart <cart number>. Pin Payments antwortet in derselben Anfrage. Vor dieser Antwort existiert keine Bestellung.

Nach einer erfolgreichen Belastung wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite mit Your card payment has been received. Wurde die Bestellung auf Pin Payments payment on hold gesetzt, zeigt die Seite Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

Antwortet Pin Payments nicht (Zeitüberschreitung, Serverfehler, unlesbare Antwort), kann die Belastung trotzdem erstellt worden sein. Die Bestellung wird dann ohne Zahlung auf Pin Payments payment on hold angelegt, und die Bestätigungsseite zeigt We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. Das erneute Absenden desselben Warenkorbs erzeugt nie eine zweite Belastung.

Pro Warenkorb läuft immer nur ein Zahlungsversuch gleichzeitig. Ein zweites Absenden erhält This order is already being paid. Please wait a moment and check your e-mail before trying again. Ein Warenkorb, der bereits eine Bestellung hat, oder ein früherer Versuch, bei dem Geld eingezogen wurde oder vermutlich eingezogen wurde, wird nicht erneut belastet; stattdessen wird die Bestellung aus diesem Versuch angelegt. Ein Kartentoken kann nur einmal verwendet werden: Nach einem fehlgeschlagenen Versuch oder wenn der Kunde die Kartendaten ändert, wird ein neues Token erstellt.

Schlägt die Zahlung fehl, wird keine Bestellung angelegt. Der Kunde bleibt im Zahlungsschritt, der Warenkorb bleibt erhalten, und eine dieser Meldungen wird angezeigt: Your card was declined. Please use another card or contact your bank.; Your card has insufficient funds. Please use another card.; Your card has expired. Please use another card.; The card security code (CVC) is incorrect.; This card type is not accepted. Please use Visa, Mastercard or American Express.; Payment failed: mit dem Grund von Pin Payments für abgelehnte Daten; Your card details have expired. Please enter them again and retry., wenn das Token nicht verwendet werden kann; The secure card form could not be loaded. Please reload the page or choose another payment method., wenn Pin.js nicht geladen wird; Card payments are temporarily unavailable. Please try again later or choose another payment method., wenn Pin Payments den Secret Key ablehnt; Your payment could not be processed. Please try again or choose another payment method. bei anderen Fehlern. Der technische Grund wird im Protokoll festgehalten.

Das Modul hat keinen 3-D-Secure-Ablauf. Verlangt Ihr Pin-Payments-Konto 3-D Secure, bleibt die Belastung ausstehend, es wird keine Bestellung angelegt, und der Kunde sieht Your card payment could not be completed (additional verification is required). Please try another card or another payment method. Es gibt keinen reinen Autorisierungsmodus mit späterer Erfassung, keine gespeicherten Karten, keine Abonnements, kein Apple Pay oder Google Pay und keine Webhooks.

Bestellungen und Erstattungen

Bestellstatus

No order yet: Die Karte wurde abgelehnt, die Belastung benötigte 3-D Secure, oder der Kunde hat nicht bezahlt. Nur der Warenkorb existiert.

Payment accepted: Pin Payments hat eine erfolgreiche, erfasste Belastung genau über den Betrag und die Währung des Warenkorbs gemeldet. Die Zahlung wird mit dem Pin-Payments-Belastungstoken als Transaktions-ID erfasst, und eine Notiz zeigt den Betrag und das Belastungstoken (bei Testzahlungen zusätzlich TEST MODE).

Pin Payments payment on hold: Die Belastung muss von Ihnen geprüft werden. Die Notiz erklärt den Grund: Pin Payments hat einen anderen Betrag oder eine andere Währung als im Warenkorb belastet (die Zahlung über den belasteten Betrag wird erfasst), der Warenkorb wurde während der Zahlung geändert, die Belastung ist autorisiert, aber nicht erfasst (erfassen Sie sie im Pin-Payments-Dashboard und setzen Sie die Bestellung danach auf Zahlung akzeptiert), oder Pin Payments hat keine eindeutige Antwort gegeben (es wird keine Zahlung erfasst; suchen Sie vor dem Versand der Bestellung im Pin-Payments-Dashboard nach der Belastungsbeschreibung).

Refunded: Die Belastung wurde über das Modul vollständig erstattet.

Wird für einen Warenkorb, der bereits eine Bestellung hat, eine zweite Belastung erstellt, bleibt die Bestellung unverändert. Eine Notiz bittet Sie, dies zu prüfen und im Pin-Payments-Dashboard zu erstatten.

Block Pin Payments

Die Bestellseite zeigt einen Block Pin Payments mit einem Badge Test mode für Testzahlungen, dem Belastungstoken, dem Status, der Kartenmarke und den letzten vier Ziffern, dem belasteten Betrag, dem Bestellgesamtbetrag und dem erstatteten Betrag, der Description at Pin Payments, dem Erstattungsverlauf und den Pin Payments notes der Bestellung.

Erstattungen

Geben Sie im Block Pin Payments den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Pin Payments. Bestätigen Sie die Frage Refund this amount through Pin Payments? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten. Erstattungen sind auf den Betrag und die Währung begrenzt, die Pin Payments tatsächlich belastet hat; nach einer Abweichung bei Betrag oder Währung können Sie also bis zu dem Betrag erstatten, den der Kunde bezahlt hat, nicht bis zum Bestellgesamtbetrag. Die Erstattung wird an die Umgebung (Test oder Live) gesendet, in der die Bestellung bezahlt wurde, daher muss deren Secret Key gesetzt sein. Pin Payments verarbeitet Erstattungen asynchron, daher ist der Status meist ausstehend. Eine erfolgreiche Anfrage wird mit dem Erstattungstoken von Pin Payments und seinem Status dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht. Lehnt Pin Payments die Erstattung ab oder antwortet nicht, zeigt der Block den Fehler, und es wird keine Erstattung erfasst.

Gibt es für die Bestellung keine erfasste Belastung (Pin Payments hat keine eindeutige Antwort gegeben), zeigt der Block kein Erstattungsformular und nennt Ihnen die Beschreibung, nach der Sie im Pin-Payments-Dashboard suchen müssen.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite überweisen kein Geld über Pin Payments zurück. Im Pin-Payments-Dashboard vorgenommene Erstattungen werden nicht mit PrestaShop synchronisiert; nehmen Sie sie daher über die Bestellseite vor.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Pin Payments Gateway ist der erste Block auf Modules > Module Manager > VibeFox Pin Payments Gateway > Configure, über den 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 aktiv ist, und Ihre Domain) sowie die Schaltflächen Check now zur erneuten Prüfung des Status, Change key zur Eingabe eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-pinpayments 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 gilt für eine Domain: die Domain des Hauptshops, auch bei einer Multistore-Installation. 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 Pin Payments Kunden auf der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Der PrestaShop-Storefront weiß nicht, dass Sie im Back Office angemeldet sind, daher wird die Zahlungsart auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber nicht auf der Kasse testen. Ein Hinweis erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Erstattungen für Bestellungen, die zuvor bezahlt wurden, funktionieren weiterhin.

Läuft eine Lizenz ab, arbeitet das Modul weiter, Updates und Support erfordern aber eine Verlängerung. Der Status wird automatisch erneut geprüft, während Sie im Back Office arbeiten: 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. Das Deinstallieren oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Pin Payments erscheint nicht auf der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, beide Schlüssel des aktuellen Modus ausgefüllt sind (Test publishable key und Test secret key im Testmodus, sonst die Live-Schlüssel) und die Warenkorbwährung eine der 14 unterstützten Währungen ist. Prüfen Sie unter Payment > Preferences, ob das Modul für die Warenkorbwährung, das Land des Kunden und die Kundengruppe erlaubt ist. Die Einstellungsseite zeigt einen Fehler bei fehlenden Schlüsseln und bei einer nicht unterstützten Shop-Währung.

Die Zahlung wurde durchgeführt, aber die Bestellung ist Pin Payments payment on hold: Lesen Sie die Notizen im Block Pin Payments (siehe Bestellstatus). Hat Pin Payments keine eindeutige Antwort gegeben, suchen Sie im Pin-Payments-Dashboard nach einer Belastung mit der Beschreibung <shop name> - Cart <cart number> und versenden Sie dann die Bestellung oder erstatten Sie die Belastung im Dashboard.

Der Kunde sieht Your payment was received, but the order could not be completed automatically: Die Karte wurde belastet, aber PrestaShop konnte die Bestellung nicht anlegen (zum Beispiel, weil das Modul zwischenzeitlich deaktiviert wurde). Der Grund steht im Protokoll. Der Kunde wird gebeten, nicht erneut zu bezahlen; das erneute Absenden desselben Warenkorbs legt die Bestellung ohne neue Belastung an.

Kunden sehen Card payments are temporarily unavailable: Pin Payments hat den Secret Key abgelehnt, oder der Schlüssel des aktuellen Modus fehlt. Testschlüssel funktionieren nur im Testmodus, Live-Schlüssel nur im Live-Modus. Das Protokoll zeigt den Grund.

Bestellungen schlagen mit additional verification is required fehl: Ihr Pin-Payments-Konto verlangt 3-D Secure, das das Modul nicht unterstützt. Bitten Sie Pin Payments, die Pflicht zu 3-D Secure abzuschalten.

Das sichere Kartenformular konnte nicht geladen werden: Pin.js aus dem CDN von Pin Payments wurde im Browser nicht geladen, etwa wegen eines Script-Blockers oder eines Moduls, das Skripte zusammenführt oder verändert. Schließen Sie die Kasse von solchen Optimierungen aus.

Pin Payments hat nicht geantwortet: Das Kartentoken wurde im Browser nicht innerhalb von 30 Sekunden erstellt. Der Kunde kann die Verbindung prüfen und es erneut versuchen; es wurde nichts belastet.

Zahlung fehlgeschlagen mit einem Grund von Pin Payments: Pin Payments hat die Belastungsdaten abgelehnt, zum Beispiel einen Betrag unter dem Mindestbetrag für die Währung. Der Kunde sieht den Grund, und das Protokoll enthält den Fehlercode.

Erstattung schlägt fehl: Lesen Sie die Meldung im Block. Eine Meldung zum TEST- oder LIVE-Modus bedeutet, dass der Secret Key des Modus, in dem die Bestellung bezahlt wurde, leer ist. Pin Payments did not confirm the refund bedeutet, dass keine Antwort kam; prüfen Sie die Belastung im Pin-Payments-Dashboard, bevor Sie es erneut versuchen. at most zeigt den Betrag an, der von der Belastung noch erstattet werden kann.

Testzahlungen: Der Testmodus verwendet die Testumgebung und die Testschlüssel. Verwenden Sie die Testkarten aus der Entwicklerdokumentation von Pin Payments, zum Beispiel 4200 0000 0000 0000 (erfolgreich) oder 4100 0000 0000 0001 (abgelehnt), mit einem beliebigen zukünftigen Ablaufdatum und einem beliebigen CVC. Bestellungen behalten den Modus, in dem sie bezahlt wurden, sodass Erstattungen nach einem Moduswechsel an die richtige Umgebung gehen.

Fehler finden: Fehler werden immer im Protokoll geschrieben; siehe das Feld Log auf der Modulseite. Aktivieren Sie Debug log, um jeden API-Aufruf zu sehen.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Pin Payments Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete data on uninstall aktiv, werden die Gateway-Einstellungen und das Protokoll entfernt. Ist die Option aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Belastungen und Erstattungen bei Pin Payments sowie der Bestellstatus Pin Payments payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen auch nach einer Neuinstallation erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Pin Payments ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist nicht mit Pin Payments verbunden und wird nicht von Pin Payments unterstützt.