VibeFox Tap 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.

Shop-Währung: AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR oder USD. Bei Warenkörben in anderen Währungen wird die Zahlungsart im Bestellvorgang ausgeblendet.

Internetzugang zu Ihrem Shop: Tap sendet das Zahlungsergebnis an einen Webhook auf Ihrem Shop, daher muss die Website aus dem Internet erreichbar sein. Die Webhook-URL wird bei jeder Zahlung übermittelt; im Tap-Dashboard muss nichts eingerichtet werden.

Tap-Konto: Sie benötigen die API-Schlüssel aus Ihrem Tap-Dashboard (goSell, API-Zugangsdaten). Testschlüssel beginnen mit pk_test_ / sk_test_, Live-Schlüssel mit pk_live_ / sk_live_. Der geheime Schlüssel wird immer benötigt; der öffentliche Schlüssel nur für das Checkout-Popup. Welche Zahlungsarten angeboten werden (mada, KNET, Benefit und andere) und die Domain-Verifizierung für Apple Pay richten Sie in Ihrem Tap-Konto ein.

VibeFox-Lizenzschlüssel: Erwerb auf 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.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später VibeFox Tap Payments 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. Geben Sie Ihre Tap-Test- und Live-Schlüssel ein, wählen Sie die Zahlungsaktion, den Checkout-Typ und die Sprache der Tap-Seite (siehe Konfiguration).

5. Aktivieren Sie Enable / Disable und klicken Sie auf Save. Testen Sie mit den Tap-Testkarten und deaktivieren Sie danach Test mode.

Bei der Installation legt das Modul zwei Bestellstatus an: Tap payment authorized und Tap 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 Tap Payments > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder zeigt die Seite Test mode is on: payments use your Tap test keys and no real money is charged. oder Live mode: real payments are accepted. an. Sie warnt außerdem, wenn die Schlüssel des aktuellen Modus fehlen (die Zahlungsart wird dann im Bestellvorgang nicht angezeigt), und wenn die Standardwährung des Shops nicht über Tap angeboten wird.

Beim Speichern wird ein Schlüssel mit einem für sein Feld falschen Präfix nicht gespeichert: Der bisherige Wert bleibt erhalten, die übrigen Einstellungen werden gespeichert, und es erscheint eine Meldung wie Test secret key was not saved: a Tap key for this field starts with "sk_test_".. Ein Live-Schlüssel in einem Testfeld wird zum Beispiel abgelehnt. Ein leerer Title wird nicht akzeptiert: Die Seite zeigt Enter a title for the payment method. und es wird nichts gespeichert.

Tap Payments

Der Abschnittstitel zeigt außerdem TEST oder LIVE für den aktuellen Modus an.

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

Title: der Name der Zahlungsart, der im Bestellvorgang angezeigt wird. Er wird auch als Zahlungsart in der Bestellung gespeichert. Standard: Tap Payments. Pflichtfeld.

Description: der Text, der im Bestellvorgang unter der Zahlungsart angezeigt wird. Standard: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Tap-API-Schlüssel

Ihre Schlüssel finden Sie im Tap-Dashboard (goSell, API-Zugangsdaten). Testschlüssel beginnen mit pk_test_ / sk_test_, Live-Schlüssel mit pk_live_ / sk_live_.

Test mode: verwendet die Testschlüssel, es wird kein echtes Geld belastet. Zahlungen, Statusabfragen, Erfassungen und Erstattungen verwenden immer die Schlüssel des Modus, in dem die Zahlung erfolgte. Eine Testzahlung wird also auch nach dem Wechsel auf Live mit dem Testschlüssel geprüft und erstattet. Standard: an. Solange er aktiv ist, sehen Kunden unter der Zahlungsart Test mode: no real payment will be made.

Test publishable key: beginnt mit pk_test_. Wird für das Popup benötigt.

Test secret key: beginnt mit sk_test_.

Live publishable key: beginnt mit pk_live_. Wird für das Popup benötigt.

Live secret key: beginnt mit sk_live_.

Merchant ID: optional. Ihre Tap-Merchant-ID; nur nötig, wenn Tap Sie gebeten hat, Zahlungen an ein bestimmtes Händlerkonto weiterzuleiten.

Gespeicherte geheime Schlüssel werden nie wieder angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. an. Geben Sie nur dann einen neuen Wert ein, wenn Sie den Schlüssel ändern möchten. Die öffentlichen Schlüssel sind nicht geheim und bleiben sichtbar.

Clear saved secrets: Setzen Sie ein Häkchen bei einem geheimen Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Zahlung

Payment action: was mit dem Geld geschieht, wenn der Kunde bezahlt.

Checkout type: wo der Kunde bezahlt.

Tap page language: English (Standard) oder Arabic.

Zahlungsbenachrichtigungen (Webhook)

Tap sendet das Zahlungsergebnis an die URL, die in diesem Abschnitt unter Webhook URL angezeigt wird. Mit SEO-freundlichen URLs sieht sie so aus: https://your-shop/module/wcp_tap_payment_gateway/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Die URL wird bei jeder Zahlung übermittelt, daher muss im Tap-Dashboard nichts eingerichtet werden. Stellen Sie nur sicher, dass sie aus dem Internet erreichbar ist (nicht durch eine Firewall oder HTTP-Authentifizierung blockiert). Jede Benachrichtigung wird mit der hashstring-Signatur geprüft (HMAC-SHA256 mit dem geheimen Schlüssel des Modus, in dem die Zahlung erfolgte). Webhooks ohne gültige Signatur werden abgelehnt. Selbst eine signierte Benachrichtigung wird nicht ungeprüft übernommen: Das Modul liest die Zahlung erneut über die Tap-API aus, bevor es die Bestellung anlegt oder ändert. Ohne funktionierenden Webhook wird die Bestellung nur angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Erweitert

Debug log: protokolliert Zahlungsereignisse in logs/tap_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web gelesen werden. Fehler und Warnungen werden immer protokolliert; aktivieren Sie diese Option, um außerdem jedes Zahlungsereignis zu protokollieren. Das Protokoll enthält nie Schlüssel, Karten- oder Kundendaten. 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: wenn aktiv, entfernt die Deinstallation des Moduls die Gateway-Einstellungen und das Protokoll. Zahlungsdatensätze der Bestellungen bleiben erhalten. Standard: aus.

Bestellvorgang

Im Zahlungsschritt wählt der Kunde die Zahlungsart (standardmäßig Tap Payments) und bestätigt die Bestellung. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Tap payment page: das Modul erstellt eine Tap-Belastung (bzw. eine Autorisierung im Modus Authorize only) über die Warenkorbsumme in der Warenkorbwährung mit der Beschreibung Cart # und der Warenkorbnummer und leitet den Kunden zur Tap-Zahlungsseite weiter. Name, E-Mail-Adresse und Telefonnummer des Kunden werden an Tap übergeben. Dort wählt der Kunde eine Karte, mada, KNET, Benefit, Apple Pay oder Google Pay (je nach Aktivierung in Ihrem Tap-Konto) und zahlt. Kann Tap die Zahlung nicht starten, bleibt der Kunde im Bestellvorgang mit The Tap payment could not be started. Please try again or choose another payment method. und der Grund wird im Protokoll festgehalten.

Tap checkout popup: der Kunde gelangt zur Seite Tap payment des Moduls, wo sich das Tap-Zahlungsformular öffnet. Die Seite zeigt außerdem den Link Pay on the Tap payment page instead. Wird das Fenster geschlossen, öffnet die Schaltfläche Pay now es erneut. Lässt sich das Formular nicht laden, wird der Kunde gebeten, die Tap-Zahlungsseite zu verwenden. Ein Neuladen der Seite verwendet denselben Zahlungsversuch.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Tap sie bestätigt: Das Modul liest die Zahlung über die Tap-API mit dem Schlüssel des Zahlungsmodus aus, prüft, dass sie sich auf diesen Warenkorb bezieht und vom Bestellvorgang dieses Warenkorbs gestartet wurde, und vergleicht Betrag und Währung mit dem Warenkorb. Allein die Tap-ID in der Rückkehr-URL legt nie eine Bestellung an. Der Webhook führt dieselbe Prüfung im Hintergrund durch. Anschließend wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite. Bei einer autorisierten Zahlung zeigt die Seite Your payment has been authorized. We will process the order as soon as the payment is captured.; bei einer Bestellung auf Halten Your payment is being reviewed. We will contact you if anything else is needed.

Hat Tap die Zahlung bei der Rückkehr des Kunden noch nicht bestätigt, zeigt eine Seite Payment confirmation den Text We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again. mit den Schaltflächen Check again und Back to checkout. Der Webhook legt die Bestellung an, sobald er eingeht.

Wurde die Zahlung abgelehnt, abgebrochen oder storniert, wird keine Bestellung angelegt. Der Kunde kehrt zum Bestellvorgang zurück mit Your payment was not completed. Please try again or choose another payment method. (mit dem Grund von Tap, wenn Tap einen angibt). Eine unvollständige Zahlung zeigt The payment was not completed. You can try again or choose another payment method. Der Warenkorb bleibt erhalten und kann erneut bezahlt werden.

Weitere Meldungen im Bestellvorgang: Tap does not accept payments in, gefolgt von der Währung, wenn die Warenkorbwährung nicht unterstützt wird, sowie The order total must be greater than zero to pay with Tap.

Der Webhook funktioniert auch, während der Shop im Wartungsmodus ist, und wird nicht durch die Länderbeschränkung Ihres Shops blockiert.

Das Modul bietet keine gespeicherten Karten oder Tokenisierung, keine Abonnements und keine Kartenfelder, die in Ihren Bestellvorgang eingebettet sind. Capture Tap payment erfasst immer die Bestellsumme; eine Teilerfassung wird nicht unterstützt.

Bestellungen und Erstattungen

Bestellstatus

Noch keine Bestellung: Der Kunde wurde zu Tap weitergeleitet und hat noch nicht bezahlt, oder Tap hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Payment accepted: Tap hat eine erfasste Zahlung bestätigt. Die Zahlung wird mit der Tap-Charge-ID (chg_...) als Transaktions-ID erfasst; eine Notiz zeigt Betrag, Charge-ID, Zahlungsart und bei Testzahlungen den Hinweis auf den Testmodus.

Tap payment authorized: die Zahlung wurde nur autorisiert und wartet auf Erfassung oder Stornierung.

Tap payment on hold: der gezahlte Betrag oder die Währung wich vom Warenkorb ab (Tap: amount/currency mismatch — manual review required.), oder die Zahlung kam ein, nachdem die Bestellung storniert worden war. Die Notiz erklärt es. Prüfen Sie die Bestellung und bearbeiten Sie sie, oder erstatten Sie die Zahlung.

Canceled: die Autorisierung wurde mit Void Tap authorization storniert, sodass die reservierten Mittel freigegeben wurden.

Refunded: die Zahlung wurde über das Modul vollständig erstattet.

Ein fehlgeschlagener Versuch ändert nie eine bezahlte, autorisierte oder stornierte Bestellung. Trifft eine zweite erfolgreiche Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert. Eine Notiz weist auf eine doppelte Zahlung hin und bittet Sie, sie im Tap-Dashboard zu erstatten. Eine Zahlung, die sich auf den Warenkorb bezieht, aber nicht vom Bestellvorgang gestartet wurde, wird nur vermerkt.

Tap-Zahlungsblock

Die Bestellseite zeigt einen Block Tap payment mit der Tap-ID, der Autorisierung und der Belastung, dem Modus (ein Badge Test mode für Testzahlungen), dem Zahlungsstatus und der Zahlungsart, Charged / refunded, dem Erstattungsverlauf, den Zahlungsversuchen des Warenkorbs und den Payment notes der Bestellung. Die Schaltflächen des Blocks funktionieren direkt auf der Bestellseite; Sie benötigen das Recht, Bestellungen zu bearbeiten, nicht den Zugriff auf die Moduleinstellungen.

Erfassen und Stornieren

Im Modus Authorize only öffnen Sie die Bestellung im Status Tap payment authorized. Capture Tap payment (mit der Bestellsumme auf der Schaltfläche) erfasst die Bestellsumme nach der Frage Capture the reserved funds of this order through Tap?; danach wird die Bestellung zu Payment accepted. Void Tap authorization fragt Release the reserved funds? The order will be canceled., gibt die Mittel frei und setzt die Bestellung auf Canceled. Lehnt Tap die Aktion ab, wird im Block ein Fehler angezeigt und zu den Notizen hinzugefügt. Wird eine Autorisierung direkt im Tap-Dashboard erfasst, markiert der Webhook die Bestellung als bezahlt; Erstattungen für diese Zahlung müssen im Tap-Dashboard vorgenommen werden.

Erstattungen

Geben Sie im Block Tap payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Tap. Bestätigen Sie die Frage Refund this amount through Tap? This cannot be undone. Vollständige und teilweise Erstattungen werden für erfasste Tap-Belastungen unterstützt. Sie können bis zu dem Betrag und der Währung erstatten, die Tap tatsächlich belastet hat, auch wenn die Bestellung später bearbeitet wurde. Die Erstattung wird mit dem geheimen Schlüssel des Modus gesendet, in dem die Zahlung erfolgte; dieser Schlüssel muss also hinterlegt sein. Eine von Tap akzeptierte Erstattung wird mit der Tap-Erstattungs-ID und dem Status in den Erstattungsverlauf und die Notizen eingetragen. Lehnt Tap sie ab, zeigt der Block den Fehler an und es wird keine Erstattung erfasst. Eine vollständige Erstattung setzt die Bestellung auf Refunded; eine teilweise Erstattung ändert den Status nicht. Bei einer autorisierten Bestellung sind Erstattungen erst möglich, wenn die Autorisierung erfasst wurde. Eine Bestellung auf Halten nach einer Betrags- oder Währungsabweichung wird im Tap-Dashboard erstattet.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Tap zurück. Im Tap-Dashboard vorgenommene Erstattungen erscheinen nicht in PrestaShop.

Lizenzschlüssel

Das Modul arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Tap Payments ist der erste Block auf Modules > Module Manager > VibeFox Tap Payments > Configure, oberhalb der Einstellungen. Geben 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 zum erneuten Prüfen des Status, Change key zum Eingeben eines anderen Schlüssels und Remove key zum Entfernen des Schlüssels aus diesem Shop. Darunter stehen die Zeile Product: presta-payment-tap 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, 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. Nachdem sich die Shop-Adresse geändert hat 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-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 Tap Payments Kunden im Bestellvorgang 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 einrichten, bevor Sie einen Schlüssel kaufen, aber es nicht im Bestellvorgang testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Reiter Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen, Erfassung und Stornierung funktionieren weiter.

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

Fehlerbehebung

Tap Payments erscheint nicht im Bestellvorgang: prüfen Sie, ob die Lizenz aktiv ist, Enable / Disable eingeschaltet ist und der aktuelle Modus einen geheimen Schlüssel hat (und einen öffentlichen Schlüssel, wenn Checkout type das Popup ist). Prüfen Sie, dass die Warenkorbwährung eine der Währungen AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR oder USD 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 eine Warnung bei fehlenden Schlüsseln und einer nicht unterstützten Shop-Währung an.

Die Zahlung ist durchgegangen, aber es wurde keine Bestellung angelegt: der Webhook kann Ihren Shop nicht erreichen. Prüfen Sie, dass die unter Webhook URL angezeigte URL aus dem Internet erreichbar ist (keine Firewall oder HTTP-Authentifizierung), und aktivieren Sie das Debug log, um die Antworten im Feld Log zu sehen. Die Bestellung wird auch angelegt, wenn der Kunde von Tap zurückkehrt.

Webhook answers invalid signature: die Benachrichtigung wurde nicht mit dem geheimen Schlüssel des Zahlungsmodus signiert. Prüfen Sie die geheimen Schlüssel in den Einstellungen.

Webhook answers gateway not configured: der geheime Schlüssel des Zahlungsmodus (Test oder Live) ist leer. Geben Sie ihn ein.

Webhook answers verification failed: die Tap-API war nicht erreichbar, um die Zahlung zu prüfen. Tap wiederholt den Webhook später.

Webhook answers order not found: die Benachrichtigung nennt einen Warenkorb, zu dem es in diesem Shop keinen Tap-Zahlungsversuch gibt.

Webhook answers busy, retry later or order could not be updated, retry later: die Bestellung wurde im selben Moment von einer anderen Anfrage bestätigt, oder die Bestellung konnte nicht angelegt werden (zum Beispiel, weil das Modul deaktiviert ist). Tap wiederholt den Webhook. Den Grund finden Sie im Feld Log.

Ein Schlüssel wird nicht gespeichert: der Schlüssel muss mit dem Präfix seines Feldes beginnen: pk_test_, sk_test_, pk_live_ oder sk_live_.

Der Kunde sieht The Tap payment could not be started: sehen Sie im Feld Log auf der Modulseite nach. Dort wird ein falscher Schlüssel oder eine abgelehnte Anfrage protokolliert.

Der Kunde sieht We could not match this payment to an order: die Zahlung gehört nicht zu diesem Warenkorb oder wurde nicht vom Bestellvorgang gestartet. Falls Geld abgebucht wurde, prüfen Sie die Zahlung im Tap-Dashboard.

Die Bestellung ist Tap payment on hold: lesen Sie die Notizen im Block Tap payment. Der gezahlte Betrag oder die Währung stimmte nicht mit dem Warenkorb überein, oder die Zahlung kam an, nachdem die Bestellung storniert worden war.

Erstattung schlägt mit einer Meldung zum Modus fehl: die Zahlung erfolgte im Test- oder Live-Modus, und für diesen Modus ist kein geheimer Schlüssel hinterlegt. Geben Sie ihn ein und versuchen Sie es erneut. Meldet der Block, dass keine erfasste Tap-Belastung gefunden wurde, erstatten Sie die Zahlung im Tap-Dashboard.

Entwickler-Hooks: die Hooks actionWcpTapChargePayload, actionWcpTapSupportedCurrencies und actionWcpTapCurrencyDecimals ermöglichen es Entwicklern, die Zahlungsanfrage, die unterstützten Währungen und die Dezimalstellen der Währungen zu ändern.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Tap Payments 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 deaktiviert, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Tap-Zahlungsversuche und -Erstattungen sowie die Bestellstatus Tap payment authorized und Tap payment on hold bleiben immer erhalten, sodass früher bezahlte Bestellungen nach einer Neuinstallation weiterhin erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Tap Payments ist eine Marke ihres jeweiligen Inhabers. Dieses Modul steht in keiner Verbindung zu Tap Payments und wird nicht von Tap Payments unterstützt.