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

Währung: Indonesische Rupiah (IDR). Midtrans rechnet ausschließlich in IDR ab, daher wird die Zahlungsmethode nur angeboten, wenn die Warenkorbwährung IDR ist. Eine Währungsumrechnung findet nicht statt. Fügen Sie die Währung IDR unter International > Localization hinzu, falls Ihr Shop sie noch nicht hat.

Midtrans-Konto: Sie benötigen den Server Key aus Midtrans Dashboard > Settings > Access Keys, sowohl im Sandbox-Dashboard als auch im Production-Dashboard. Verwendet wird nur der Server Key. Der Client Key wird für Snap Redirect nicht benötigt. Die Zahlungsmethoden selbst (GoPay, QRIS, virtuelle Konten und andere) werden in Ihrem Midtrans-Konto aktiviert.

VibeFox-Lizenzschlüssel: wird auf vibefox.net gekauft. 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 später VibeFox Midtrans Payment Gateway 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. Tragen Sie die Server Keys ein und kopieren Sie die URL für Zahlungsbenachrichtigungen in das Midtrans-Dashboard (siehe Konfiguration).

5. Aktivieren Sie Enable/Disable und klicken Sie auf Save. Testen Sie in Sandbox und stellen Sie danach Environment auf Production um.

Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting Midtrans payment und Midtrans payment on hold. PrestaShop bietet ein neues Zahlungsmodul für alle Währungen, Länder und Kundengruppen an. Sie können dies unter Payment > Preferences einschränken. Das Modul muss für die Währung IDR erlaubt bleiben.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox Midtrans Payment Gateway > Configure. Jeder Abschnitt hat eine eigene Schaltfläche Save, die die gesamte Seite speichert. Oberhalb der Felder warnt die Seite, wenn der Server Key der gewählten Umgebung fehlt (die Zahlungsmethode wird dann an der Kasse ausgeblendet) und wenn die Standardwährung des Shops nicht IDR ist. Solange Sandbox gewählt ist, wird der Hinweis Sandbox mode: payments are simulated, no real money is charged. angezeigt.

Midtrans

Enable/Disable: Enable Midtrans payments schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Titel der Zahlungsmethode, den Kunden an der Kasse sehen. Er ist zugleich der Name der Zahlungsmethode, der in der Bestellung gespeichert wird. Standard: Midtrans. Pflichtfeld.

Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. Im Sandbox-Modus wird die Zeile SANDBOX MODE: no real money is charged. ergänzt.

API-Zugangsdaten

Kopieren Sie den Server Key aus Midtrans Dashboard > Settings > Access Keys. Der Abschnitt enthält Links zum Production- und zum Sandbox-Dashboard.

Environment: welche Midtrans-Umgebung neue Zahlungen verwenden. Beim Umschalten werden der Schlüssel und die API der gewählten Umgebung verwendet. Zahlungen behalten die Umgebung, in der sie getätigt wurden, für Erstattungen und Benachrichtigungen. Standard: Sandbox.

Production Server Key: beginnt mit Mid-server-. Halten Sie ihn geheim.

Sandbox Server Key: beginnt mit SB-Mid-server-.

Gespeicherte Schlüssel werden nie erneut angezeigt. Das Feld bleibt leer und zeigt Saved — leave empty to keep it. Geben Sie einen neuen Wert nur ein, wenn Sie ihn ändern möchten.

Clear saved keys: Markieren Sie einen Schlüssel und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

URL für Zahlungsbenachrichtigungen

Die Benachrichtigung teilt Ihrem Shop mit, dass eine Zahlung erfolgt ist. Das Feld Notification URL zeigt die zu verwendende URL. Mit schönen URLs sieht sie etwa so aus: https://your-shop/module/wcp_midtrans_payment_gateway/webhook, gegebenenfalls mit einem Sprachcode wie /en/. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen, und fügen Sie sie unter Midtrans Dashboard > Settings > Payment > Notification URL ein, und zwar im Sandbox-Dashboard und im Production-Dashboard, das Sie verwenden. Öffnen Sie die URL im Browser, erscheint eine kurze Erklärung, sodass Sie prüfen können, ob sie erreichbar ist. Auch die Schaltfläche Test notification URL im Midtrans-Dashboard wird beantwortet.

Jede Benachrichtigung muss eine gültige Signatur enthalten, die mit einem Ihrer Server Keys erstellt wurde, und die Umgebung des Schlüssels muss zur Umgebung der Zahlung passen. Benachrichtigungen ohne gültige Signatur werden abgelehnt. Der Status wird dann über die Status-API von Midtrans erneut abgefragt. Das Modul verarbeitet folgende Midtrans-Transaktionsstatus:

Ohne die Benachrichtigungs-URL wird eine Bestellung nur angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt, und eine später getätigte verzögerte Zahlung wird erst erkannt, wenn der Kunde zurückkommt.

Zahlungseinstellungen

Midtrans rechnet ausschließlich in IDR ab, und Beträge werden in ganzen Rupiah übermittelt. Ergeben die Bestellpositionen nicht die gerundete Summe, wird eine Zeile Rounding adjustment an Midtrans gesendet.

Status after payment: der Bestellstatus nach einer bestätigten Zahlung.

Payment page expiry (minutes): wie lange der Kunde zahlen kann (Snap-Seite, virtuelles Konto usw.). Leer lassen oder 0 eingeben, um den Midtrans-Standard zu verwenden. Ein Wert, der keine ganze Zahl von Minuten ist, wird beim Speichern mit einer Fehlermeldung abgelehnt.

Order ID prefix: wird der Nummer vorangestellt, die an Midtrans gesendet wird, damit mehrere Shops ein Midtrans-Konto teilen können. Die Nummer besteht aus der Warenkorb-ID mit einem Zeitstempel, zum Beispiel WC-123-1700000000. Erlaubt sind nur Buchstaben, Ziffern sowie - _ . ~, bis zu 20 Zeichen; andere Zeichen werden beim Speichern entfernt. Benachrichtigungen anderer Shops werden ignoriert. Standard: WC-.

Erweitert

Debug log: schreibt API-Aufrufe und Benachrichtigungen in logs/midtrans_p_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler werden immer protokolliert. Schlüssel und 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 die Deinstallation des Moduls die Moduleinstellungen und das Protokoll. Bestellungen, ihre Midtrans-Zahlungsreferenzen und Erstattungen sowie die Bestellstatus des Moduls bleiben immer erhalten, damit ältere Bestellungen nach einer Neuinstallation noch erstattet werden können. Standard: aus.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsmethode (standardmäßig Midtrans) und bestätigt. Das Modul erstellt eine Midtrans-Snap-Transaktion für den Warenkorbbetrag in ganzen Rupiah, mit den Bestellpositionen, dem Versand, den Rabatten, der Geschenkverpackung, der Steuer sowie den Rechnungs- und Lieferdaten des Kunden, und leitet den Kunden zur Zahlungsseite von Midtrans weiter. Dort wählt der Kunde eine beliebige Methode, die in Ihrem Midtrans-Konto aktiviert ist. Zu diesem Zeitpunkt existiert noch keine Bestellung.

Nach der Zahlung kehrt der Kunde in Ihren Shop zurück. Der Rücksprung-Link markiert eine Bestellung nie als bezahlt: Die Bestellung wird erst bezahlt, nachdem Midtrans sie bestätigt hat, entweder durch die signierte Benachrichtigung oder durch eine Anfrage an die Status-API von Midtrans, wenn der Kunde zurückkehrt. Dann wird die Bestellung angelegt, und der Kunde sieht die übliche Bestellbestätigungsseite mit der verwendeten Zahlungsmethode. Bei einer verzögerten Zahlung zeigt die Seite We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. Bei einer ohne Zahlung geschlossenen Bestellung zeigt sie Your Midtrans payment was not completed. Please contact us about this order. Kann Midtrans bei der Rückkehr des Kunden nicht erreicht werden, zeigt eine Seite Payment confirmation den Hinweis We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. mit einer Schaltfläche Check again.

Hat der Kunde die Snap-Seite ohne Zahlung verlassen, kehrt er zur Kasse zurück und sieht The Midtrans payment was not completed. You can try again below. Wurde die Zahlung abgelehnt oder ist sie abgelaufen, lautet der Hinweis Your Midtrans payment was declined or has expired. Please try again or choose another payment method. Der Warenkorb bleibt erhalten. Zahlt der Kunde erneut, wird ein nicht genutztes oder ausstehendes Snap über denselben Betrag wiederverwendet. Hat sich der Betrag geändert, wird die ausstehende Transaktion zuerst bei Midtrans abgelaufen gelassen. Wurde das vorherige Snap inzwischen bezahlt, wird die Bestellung angelegt, und es wird keine neue Transaktion erstellt. Existiert die Bestellung bereits und wurde sie ohne Zahlung geschlossen, lautet der Hinweis Your Midtrans payment was declined or has expired. Please place a new order or contact us.

Kann Midtrans die Zahlung nicht starten, bleibt der Kunde an der Kasse mit einer kurzen Meldung: Could not connect to Midtrans. Please try again in a moment., Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (zum Beispiel bei einem falschen Server Key) oder dem Grund, den Midtrans nennt. Der technische Grund wird im Protokoll festgehalten. Ein Warenkorb, der nicht in IDR ist, zeigt Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

Die Benachrichtigung funktioniert auch, wenn der Shop im Wartungsmodus ist, und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.

Das Modul verwendet nur Snap Redirect. Es gibt kein Snap-Popup, kein Kartenformular auf Ihrer Website, keine gespeicherten Karten oder Ein-Klick-Zahlungen, keine Einstellungen für Ratenzahlung oder Aktionen (konfigurieren Sie die Zahlungsmethoden im Midtrans-Dashboard) und keine Abonnements. Kartenzahlungen werden sofort erfasst, ohne getrennte Autorisierung und Erfassung.

Bestellungen und Erstattungen

Bestellstatus

No order yet: Der Kunde wurde zu Midtrans weitergeleitet und hat nicht bezahlt, oder Midtrans hat die Zahlung noch nicht bestätigt. Es existiert nur der Warenkorb.

Awaiting Midtrans payment: Der Kunde hat eine verzögerte Methode (virtuelles Konto, Convenience-Store) gewählt oder eine Kartenzahlung begonnen, die nicht abgeschlossen wurde. Die Bestellung wird bezahlt, sobald Midtrans die Zahlung meldet.

Payment accepted, Delivered oder Midtrans payment on hold: Die Zahlung wurde bestätigt. Der Status richtet sich nach Status after payment. Die Zahlung wird mit der Midtrans-Transaktions-ID erfasst, und eine Notiz zeigt die Zahlungsmethode und die Midtrans-Bestellnummer.

Midtrans payment on hold: wird auch gesetzt, wenn eine Kartenzahlung zur Betrugsprüfung anliegt (challenge, noch keine Zahlung erfasst), wenn der bezahlte Betrag oder die Währung nicht zur Bestellung passte (die Bestellung wird nicht als bezahlt markiert) oder wenn eine Zahlung für eine stornierte Bestellung eingeht (die Bestellung wird nicht automatisch wieder geöffnet). Die Notiz erklärt es. Prüfen Sie die Bestellung und bearbeiten Sie sie anschließend oder erstatten Sie die Zahlung.

Canceled: die unbezahlte Transaktion ist abgelaufen oder wurde storniert. Wenn Sie eine unbezahlte Midtrans-Bestellung selbst stornieren, wird ihre ausstehende Midtrans-Transaktion, zum Beispiel ein ausgestelltes virtuelles Konto, abgelaufen, sodass sie nicht mehr bezahlt werden kann.

Payment error: die Zahlung ist fehlgeschlagen oder eine geprüfte Kartenzahlung wurde abgelehnt.

Refunded: die Zahlung wurde vollständig erstattet.

Geht eine zweite Zahlung für eine bereits bezahlte Bestellung ein, bleibt die Bestellung unverändert. Eine Notiz fordert Sie auf, die zweite Zahlung im Midtrans-Dashboard zu erstatten. Eine Zahlung für eine erstattete Bestellung fügt nur eine Notiz hinzu.

Midtrans-Zahlungsblock

Die Bestellseite zeigt einen Block Midtrans payment mit der Midtrans-Bestellnummer, der Transaktions-ID (verlinkt mit der Transaktion im Midtrans-Dashboard der Umgebung der Zahlung), der Zahlungsmethode, dem Status, dem bezahlten und erstatteten Betrag, einem Abzeichen Sandbox für Sandbox-Zahlungen, dem Erstattungsverlauf und den Midtrans notes der Bestellung.

Erstattungen

Geben Sie im Block Midtrans payment den Betrag ein (der noch nicht erstattete Betrag wird vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via Midtrans. Bestätigen Sie die Abfrage Refund this amount through Midtrans? This cannot be undone. Vollständige und teilweise Erstattungen in ganzen Rupiah werden unterstützt; ein Betrag mit Dezimalstellen wird abgelehnt. Sie benötigen das Recht, Bestellungen zu bearbeiten. Sie können bis zu dem Betrag erstatten, den Midtrans tatsächlich abgebucht hat, auch wenn die Bestellung später bearbeitet wurde. Die Erstattung wird in der Umgebung gesendet, in der die Zahlung erfolgte, daher muss der Server Key dieser Umgebung hinterlegt sein. Midtrans erlaubt API-Erstattungen nur für bestimmte Zahlungsmethoden und Transaktionsstatus (zum Beispiel abgerechnete Kartenzahlungen, GoPay-, QRIS- oder ShopeePay-Zahlungen). Akzeptiert Midtrans die Erstattung nicht, zeigt der Block den Fehler, und es wird keine Erstattung erfasst; erstatten Sie dann im Midtrans-Dashboard. Eine erfolgreiche Erstattung wird dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht. Erstattungen sind verfügbar, sobald Midtrans die Zahlung als abgerechnet gemeldet hat.

Das Modul erstellt keine Gutschriften. Die Standard-Erstattungsschaltflächen von PrestaShop auf der Bestellseite senden kein Geld über Midtrans zurück.

Im Midtrans-Dashboard vorgenommene Erstattungen gehen über die Benachrichtigung ein und werden automatisch mit dem Grund Refunded in the Midtrans dashboard dem Erstattungsverlauf hinzugefügt. Wird die gesamte Zahlung dort erstattet, wird die Bestellung auf Refunded gesetzt.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox Midtrans Payment Gateway ist der erste Block unter Modules > Module Manager > VibeFox Midtrans 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 Schlüssel maskiert, 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-midtrans 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. 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 funktioniert auf einer Domain: der 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 Midtrans Kunden an 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 Zahlungsmethode auch für Sie ausgeblendet: Sie können das Modul vor dem Kauf eines Schlüssels einrichten, aber an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

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 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

Midtrans does not appear at checkout: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist und die gewählte Environment ihren Server Key hat. Prüfen Sie, ob die Warenkorbwährung IDR ist. Prüfen Sie unter Payment > Preferences, ob das Modul für IDR, das Land des Kunden und die Kundengruppe erlaubt ist. Die Einstellungsseite zeigt eine Warnung, wenn der Schlüssel fehlt oder die Shop-Währung nicht IDR ist.

The payment went through, but no order was created: Die Benachrichtigung funktioniert nicht. Prüfen Sie, ob die URL für Zahlungsbenachrichtigungen im Midtrans-Dashboard der von Ihnen verwendeten Umgebung (Sandbox oder Production) hinterlegt ist, ob sie exakt der unter Notification URL angezeigten URL entspricht und ob sie erreichbar ist: Öffnen Sie sie im Browser, es erscheint eine kurze Erklärung. Aktivieren Sie Debug log, um die Benachrichtigungen zu sehen. Die Bestellung wird auch angelegt, wenn der Kunde nach der Zahlung in den Shop zurückkehrt.

Notification answers Invalid signature: Die Benachrichtigung wurde nicht mit Ihrem Sandbox- oder Production-Server-Key signiert. Prüfen Sie, ob die Schlüssel in den Einstellungen zu demselben Midtrans-Konto gehören wie das Dashboard, das die Benachrichtigungen sendet.

Notification answers Server key not configured: es ist kein Server Key hinterlegt. Tragen Sie ihn in den Einstellungen ein; Midtrans wiederholt die Benachrichtigung.

Notification answers Order not found — ignored: die Midtrans-Bestellnummer wurde nicht von diesem Shop vergeben, zum Beispiel von einem anderen Shop auf demselben Midtrans-Konto. Geben Sie jedem Shop ein anderes Order ID prefix.

Notification answers Environment mismatch — ignored: die Benachrichtigung wurde mit dem Schlüssel der anderen Umgebung signiert als derjenigen, in der die Zahlung erfolgte.

Notification answers Verification failed, please retry: die Status-API von Midtrans war nicht erreichbar. Midtrans wiederholt die Benachrichtigung.

Notification answers Busy, please retry: 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). Midtrans wiederholt die Benachrichtigung. Sehen Sie im Protokoll nach dem Grund.

The order is Midtrans payment on hold: lesen Sie die Midtrans notes im Block. Die Kartenzahlung wird geprüft, der bezahlte Betrag oder die Währung stimmt nicht mit der Bestellung überein, oder die Zahlung ging nach der Stornierung der Bestellung ein.

The customer sees an error when choosing Midtrans: Sehen Sie im Feld Log auf der Modulseite nach; Fehler werden immer protokolliert. Ein falscher Server Key zeigt die Meldung, dass Midtrans-Zahlungen vorübergehend nicht verfügbar sind.

Refund fails: die Zahlungsmethode oder der Transaktionsstatus erlaubt keine API-Erstattungen; erstatten Sie im Midtrans-Dashboard, die Erstattung wird dann automatisch an der Bestellung erfasst. Lautet die Meldung, dass für die Umgebung, in der die Bestellung bezahlt wurde, kein Server Key hinterlegt ist, tragen Sie diesen Schlüssel ein und versuchen Sie es erneut.

Entwickler können die an Midtrans gesendeten Daten mit dem Hook actionWcpMidtransSnapPayload ändern; die Bestellnummer und der Betrag können nicht geändert werden.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox Midtrans Payment 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 Moduleinstellungen und das Protokoll entfernt. Ist die Option aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die Midtrans-Zahlungsreferenzen und Erstattungen der Bestellungen sowie die Bestellstatus Awaiting Midtrans payment und Midtrans payment on hold bleiben immer erhalten, damit früher bezahlte Bestellungen nach einer Neuinstallation noch erstattet werden können. Bestehende Bestellungen behalten ihre Zahlungsnotizen und Transaktions-IDs.

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