VibeFox Xendit 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: IDR, PHP, VND, THB, MYR, USD oder SGD. Für andere Warenkorbwährungen wird die Zahlungsart nicht angezeigt. Welche Zahlungskanäle und Währungen tatsächlich verfügbar sind, hängt von Ihrem Xendit-Konto ab.

Xendit-Konto: Sie benötigen einen geheimen API-Schlüssel mit Schreibberechtigung für Money-in (Rechnungen) für den Testmodus und einen weiteren für den Live-Modus sowie das Webhook-Verifizierungstoken jedes Modus (siehe Konfiguration). Verwendet werden nur die geheimen Schlüssel und die Verifizierungstoken. Ein öffentlicher Schlüssel wird nicht benötigt, da der Kunde auf der von Xendit gehosteten Rechnungsseite zahlt.

VibeFox-Lizenzschlüssel: erhältlich auf vibefox.net. Ein Schlüssel funktioniert auf einer 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 VibeFox Xendit Payment Gateway später 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. Fügen Sie Ihre geheimen Xendit-Schlüssel ein, setzen Sie die Webhook-URL im Xendit-Dashboard und fügen Sie die Verifizierungstoken ein (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Legen Sie im Testmodus eine Testbestellung an und deaktivieren Sie danach Test Mode, um echte Zahlungen anzunehmen.

Bei der Installation legt das Modul den Bestellstatus Xendit payment on hold an. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können diese unter Payment > Preferences einschränken.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Über den Feldern zeigt ein Kasten den aktiven Modus: TEST MODE (Rechnungen werden mit dem geheimen Testschlüssel erstellt, und es wird kein echtes Geld abgebucht) oder LIVE MODE (Rechnungen werden mit dem geheimen Live-Schlüssel erstellt, und Kunden werden belastet). Der Kasten warnt, wenn der geheime Schlüssel des aktiven Modus fehlt oder das falsche Präfix hat (die Zahlungsart wird dann auf der Kasse ausgeblendet), und wenn das Webhook-Verifizierungstoken des aktiven Modus leer ist (Xendit-Benachrichtigungen werden dann abgelehnt, sodass Bestellungen nur angelegt werden, wenn der Kunde in Ihren Shop zurückkehrt).

Xendit

Enable/Disable: Enable Xendit 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: Xendit. Pflichtfeld.

Description: der Text, der auf der Kasse unter der Zahlungsart angezeigt wird. Standard: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

API-Schlüssel

Erstellen Sie einen geheimen API-Schlüssel mit Schreibberechtigung für Money-in (Rechnungen) unter Xendit Dashboard > Settings > Developers > API keys, einmal im Testmodus und einmal im Live-Modus. Der Schlüssel bestimmt, wo die Rechnung erstellt wird. Beim Speichern wird ein Schlüssel, der nicht mit dem Präfix seines Feldes beginnt, nicht gespeichert, und die Seite zeigt zum Beispiel Test secret key was not saved: it must start with xnd_development_. Die übrigen Einstellungen werden gespeichert.

Test Mode: erstellt Rechnungen mit dem geheimen Testschlüssel, sodass kein echtes Geld abgebucht wird. Standard: an. Deaktivieren Sie die Option, um echte Zahlungen mit dem geheimen Live-Schlüssel anzunehmen. Solange sie aktiviert ist, sehen Kunden Test mode: no real money is charged. unter der Zahlungsart.

Test Secret Key: der geheime Schlüssel des Xendit-Testmodus. Er beginnt mit xnd_development_.

Live Secret Key: der geheime Schlüssel des Xendit-Live-Modus. Er beginnt mit xnd_production_.

Gespeicherte Schlüssel und 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.

Webhooks

Der Webhook teilt Ihrem Shop mit, dass eine Rechnung bezahlt wurde. Stellen Sie im Xendit Dashboard > Settings > Developers > Webhooks die URL aus Webhook URL in diesem Abschnitt für Invoices > Invoice paid ein, im Testmodus und im Live-Modus. Optional können Sie sie auch für Invoice expired setzen. Mit aktivierten sprechenden URLs sieht sie so aus: https://your-shop/module/wcp_xendit_payment_gateway/webhook, eventuell mit einem Sprachcode wie /en/. Kopieren Sie sie genau so, wie die Einstellungen sie anzeigen.

Kopieren Sie danach das Webhook verification token jedes Modus aus dem Xendit-Dashboard in das passende Feld. Xendit sendet es im Header x-callback-token. Benachrichtigungen ohne das Token des Modus, in dem die Rechnung erstellt wurde, werden abgelehnt. Das Token belegt nur, dass die Benachrichtigung von Xendit stammt: Status, Betrag und Währung der Rechnung werden immer erneut über die Xendit-API mit dem geheimen Schlüssel dieses Modus abgefragt. Ohne Webhook wird eine Bestellung nur angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Test Webhook Verification Token: das Webhook-Verifizierungstoken des Xendit-Testmodus.

Live Webhook Verification Token: das Webhook-Verifizierungstoken des Xendit-Live-Modus.

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

Zahlung

Invoice Description: die Beschreibung, die auf der Xendit-Rechnung erscheint. Sie können die Platzhalter {order_id}, {order_number} und {site_name} verwenden. Da die Bestellung erst nach der Zahlung angelegt wird, sind {order_id} und {order_number} die Warenkorbnummer. HTML wird entfernt, und der Text wird auf 255 Zeichen gekürzt. Standard: Order #{order_id}.

Order Status After Payment: der Bestellstatus, der gesetzt wird, nachdem Xendit die Zahlung bestätigt hat.

Erweitert

Debug Log: schreibt API-Anfragen und Webhooks in logs/xendit_p_debug.log.php im Modulordner. Die Datei lässt sich nicht über das Web öffnen. Fehler und Warnungen werden immer protokolliert, auch wenn diese Option aus ist. API-Schlüssel, Token und Kundendaten werden nicht 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: Wenn die Option aktiviert ist, entfernt die Deinstallation des Moduls die Modul-Einstellungen und das Protokoll. Bestellungsdaten (Rechnungs-IDs der Bestellungen) und der Bestellstatus Xendit payment on hold bleiben immer erhalten. Standard: aus.

Kasse

Die Zahlungsart wird angezeigt, wenn die Währung des Warenkorbs IDR, PHP, VND, THB, MYR, USD oder SGD ist. Der Kunde wählt sie im Zahlungsschritt (standardmäßig Xendit) aus und bestätigt. Das Modul erstellt eine Xendit-Rechnung über den Warenkorbbetrag in der Währung des Warenkorbs und leitet den Kunden zur Xendit-Rechnungsseite weiter. IDR- und VND-Beträge werden auf ganze Zahlen gerundet, da Xendit für diese Währungen keine Dezimalstellen akzeptiert. Die E-Mail-Adresse des Kunden wird an Xendit übergeben. Auf der Rechnungsseite zahlt der Kunde mit einem der Zahlungskanäle, die in Ihrem Xendit-Konto für diese Währung aktiviert sind, zum Beispiel einem virtuellen Konto, einem E-Wallet, einem QR-Code, einer Einzelhandelsfiliale oder einer Karte. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Die Bestellung wird erst als bezahlt markiert, wenn Xendit die Zahlung bestätigt: durch den Webhook oder durch eine serverseitige Anfrage an die Xendit-API, wenn der Kunde zurückkehrt. Danach wird die Bestellung angelegt, und der Kunde sieht die Standard-Bestellbestätigungsseite. Hat Xendit die Zahlung noch nicht bestätigt, zeigt eine Seite Payment confirmation den Hinweis Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. mit den Schaltflächen Check again und Back to checkout. Der Webhook legt die Bestellung an, sobald er eintrifft.

Schlägt die Rechnung fehl oder läuft sie ab, schickt Xendit den Kunden zurück. Das Modul prüft zuerst die Rechnung (sie könnte in einem anderen Tab bezahlt worden sein) und lässt sie dann ablaufen, sodass sie nicht mehr bezahlt werden kann. Der Kunde landet wieder auf der Kasse mit The Xendit payment was not completed. You can try again or choose another payment method. Der Warenkorb bleibt erhalten.

Ein Kunde kann denselben Warenkorb erneut bezahlen. Wenn Warenkorbbetrag, Währung und Modus unverändert sind und die offene Rechnung noch mindestens fünf weitere Minuten gültig ist, wird der Kunde zu derselben Rechnung geschickt. Andernfalls wird die alte Rechnung zuerst ablaufen gelassen und eine neue erstellt, sodass es nie zwei offene Rechnungen für einen Warenkorb gibt. War die alte Rechnung bereits bezahlt, wird statt einer neuen Zahlung die Bestellung angelegt.

Kann Xendit die Zahlung nicht starten, bleibt der Kunde auf der Kasse mit einer kurzen Meldung, zum Beispiel Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method., einer Meldung, dass die Währung für Ihr Konto nicht akzeptiert wird, oder dass der Bestellbetrag außerhalb der Betragsgrenzen von Xendit liegt. Der technische Grund wird im Protokoll gespeichert. Ein Warenkorb mit der Summe null kann nicht mit Xendit bezahlt werden.

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

Die Zahlung erfolgt immer auf der Xendit-Seite. Das Modul bietet keine Erstattungen aus dem Back Office, keine gespeicherten Karten, Abonnements oder wiederkehrenden Zahlungen, keine Karten- oder E-Wallet-Felder auf der Kasse, keine getrennte Autorisierung und Erfassung und keine xenPlatform-Unterkonten.

Bestellungen

Bestellstatus

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

Payment accepted or Delivered: Die Zahlung wurde bestätigt. Der Status folgt Order Status After Payment. Die Zahlung wird mit der Xendit-Rechnungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Rechnungs-ID, den bezahlten Betrag, den Zahlungskanal und den Modus.

Xendit payment on hold: Die bezahlte Rechnung entsprach nicht dem Warenkorbbetrag oder der Währung, oder es wurde weniger als der Gesamtbetrag bezahlt (zum Beispiel wurde der Warenkorb geändert, nachdem die Rechnung erstellt wurde). Die Notiz erklärt es. Prüfen Sie die Zahlung im Xendit-Dashboard und schließen Sie dann die Bestellung ab oder erstatten Sie die Zahlung. Wird später eine andere Rechnung desselben Warenkorbs mit dem richtigen Betrag bezahlt, wird die Zahlung erfasst und die Bestellung wechselt in den bezahlten Status.

Wird eine Rechnung für eine bereits stornierte oder erstattete Bestellung bezahlt, ändert sich der Bestellstatus nicht. Eine Notiz bittet Sie, die Zahlung im Xendit-Dashboard zu erstatten oder die Bestellung manuell wiederherzustellen. Wird eine zweite Rechnung für eine bereits bezahlte Bestellung bezahlt, bleibt die Bestellung unverändert, und eine Notiz bittet Sie, die doppelte Zahlung im Xendit-Dashboard zu erstatten.

Block Xendit payment

Die Bestellseite zeigt einen Block Xendit payment mit der Rechnungs-ID, dem Modus (mit einem Badge Test mode für Testzahlungen), dem Zahlungsstatus, einer Liste aller Rechnungen der Bestellung (Datum, Rechnung, externe ID, Betrag und bezahlter Betrag, Status, Zahlungskanal) und den Payment notes der Bestellung.

Erstattungen

Erstattungen werden nicht von Ihrem Shop aus an Xendit gesendet. Erstatten Sie die Zahlung im Xendit-Dashboard (suchen Sie nach der Rechnungs-ID, die im Block Xendit payment angezeigt wird) und erfassen Sie die Erstattung manuell in der Bestellung. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Xendit zurück.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Xendit Payment Gateway ist der erste Block unter Modules > Module Manager > VibeFox Xendit Payment 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 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-xendit 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 auf einer Domain: der Domain des Hauptshops, auch bei einer Multistore-Konfiguration. 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 Xendit auf der Kasse nicht angezeigt. Versucht ein Kunde trotzdem zu zahlen, sieht er 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 auf der Kasse nicht testen. Ein Hinweis erscheint unter Modules > Module Manager auf der Registerkarte 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 erfordern eine Verlängerung. Der Status wird während der Arbeit im Back Office automatisch erneut geprüft: einmal am Tag in den ersten 14 Tagen nach Eingabe des Schlüssels, danach einmal pro Woche. Ein Cron-Job ist nicht nötig. Deinstallation oder Zurücksetzen des Moduls entfernt immer den Lizenzschlüssel und den Lizenzstatus.

Fehlerbehebung

Xendit erscheint nicht auf der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, der aktive Modus einen geheimen Schlüssel mit dem richtigen Präfix hat (Test Secret Key mit xnd_development_ im Testmodus, Live Secret Key mit xnd_production_ im Live-Modus) und die Währung des Warenkorbs IDR, PHP, VND, THB, MYR, USD oder SGD ist. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt oder falsch 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 Zahlung ist durchgegangen, aber es wurde keine Bestellung angelegt: Der Webhook funktioniert nicht. Prüfen Sie im Xendit-Dashboard des verwendeten Modus (Test oder Live), ob die in Webhook URL angezeigte URL für Invoice paid eingetragen ist und ob das Verifizierungstoken dieses Modus im passenden Feld gespeichert ist. Das Xendit-Dashboard zeigt für jeden Webhook die Antwort Ihres Shops an. Die Bestellung wird auch angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Webhook answers Webhook verification token is not configured: Es ist kein Verifizierungstoken gesetzt. Fügen Sie das Token in die Einstellungen ein.

Webhook answers Unauthorized: Das von Xendit gesendete Token stimmt mit keinem Token in den Einstellungen überein. Kopieren Sie das Token des richtigen Modus erneut.

Webhook answers Token does not match the mode of this invoice: Die Rechnung wurde im anderen Modus erstellt. Eine Testbenachrichtigung bestätigt nie eine Live-Zahlung und umgekehrt. Richten Sie Webhook und Token in dem Modus ein, in dem der Warenkorb bezahlt wurde.

Webhook answers Ignored: not an invoice of this store: Die Rechnung wurde nicht von diesem Shop erstellt, zum Beispiel durch eine andere Integration auf demselben Xendit-Konto. Die Schaltfläche Test im Xendit-Dashboard erhält ebenfalls diese Antwort, was bestätigt, dass URL und Token funktionieren. Ignored: unknown order und Ignored: unknown invoice bedeuten, dass der Warenkorb oder die Rechnung diesem Shop nicht bekannt ist.

Webhook answers Temporary error: Die Xendit-API konnte zur Prüfung der Rechnung nicht erreicht werden, der geheime Schlüssel des Modus der Rechnung fehlt, der Warenkorb wurde im selben Moment von einer anderen Anfrage aktualisiert, oder die Bestellung konnte nicht angelegt werden (zum Beispiel weil das Modul deaktiviert ist). Xendit wiederholt den Webhook. Prüfen Sie, ob beide geheimen Schlüssel gesetzt sind, wenn Zahlungen in beiden Modi gestartet wurden, und aktivieren Sie Debug Log, um den Grund zu sehen.

Die Webhook-URL zeigt im Browser Method not allowed: Das ist normal. Die URL akzeptiert nur Anfragen von Xendit.

Ein Schlüssel wird nicht gespeichert: Der Wert beginnt nicht mit dem Präfix seines Feldes. Testschlüssel beginnen mit xnd_development_, Live-Schlüssel mit xnd_production_.

Der Kunde sieht This payment method is temporarily unavailable: Xendit hat die Anfrage abgelehnt, zum Beispiel weil der geheime Schlüssel falsch ist oder keine Schreibberechtigung für Money-in (Rechnungen) hat. Sehen Sie im Feld Log auf der Modulseite nach. Eine Meldung zu den Rechnungsdaten bedeutet, dass Xendit die Anfragedaten nicht akzeptiert hat, zum Beispiel die E-Mail-Adresse.

Der Kunde sieht A payment for this order was already received by Xendit and is being reviewed: Eine frühere Rechnung dieses Warenkorbs wurde bezahlt, aber die Bestellung konnte noch nicht bestätigt werden. Prüfen Sie die Zahlung im Xendit-Dashboard und im Protokoll.

Der Kunde sieht We could not match this payment to an order: Der Rückkehrlink von Xendit gehört zu keinem Warenkorb dieses Shops, oder es konnte keine Rechnung des Warenkorbs zugeordnet werden. Prüfen Sie die Zahlung im Xendit-Dashboard und im Protokoll.

Bestellung ist nach der Zahlung Xendit payment on hold: Lesen Sie die Notizen im Block Xendit payment. Der bezahlte Betrag oder die Währung wich vom Warenkorb ab. Schließen Sie die Bestellung ab oder erstatten Sie die Zahlung im Xendit-Dashboard.

Für Entwickler stellt das Modul die Hooks actionWcpXenditInvoiceRequest, actionWcpXenditSupportedCurrencies und actionWcpXenditCurrencyDecimals bereit, um die Rechnungsanfrage, die Währungsliste und die Anzahl der Dezimalstellen je Währung zu ändern.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Xendit Payment Gateway und wählen Sie Uninstall. Der Lizenzschlüssel und der Lizenzstatus dieses Moduls werden immer entfernt. Ist Delete Data on Uninstall aktiviert, werden die Modul-Einstellungen und das Protokoll entfernt. Ist die Option aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Xendit-Rechnungsdaten der Bestellungen und der Bestellstatus Xendit payment on hold bleiben immer erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

Xendit ist eine Marke ihres jeweiligen Inhabers. Dieses Modul ist weder mit Xendit verbunden noch von Xendit unterstützt.