VibeFox MercadoPago for WooCommerce — Hilfe

Anforderungen

WordPress: 6.0 oder neuer.

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

PHP: 8.0 oder neuer.

Shopwährung: die Währung des Landes Ihres MercadoPago-Kontos: ARS (Argentinien), BRL (Brasilien), CLP (Chile), COP (Kolumbien), MXN (Mexiko), PEN (Peru) oder UYU (Uruguay). MercadoPago belastet in der Kontowährung und rechnet nicht um. Deshalb wird die Zahlungsmethode ausgeblendet, wenn die Währungen nicht übereinstimmen.

MercadoPago-Konto: Sie benötigen eine Anwendung im MercadoPago-Entwicklerportal (Your integrations > your application > Credentials) mit den Testzugangsdaten (beginnen mit TEST-) und den Produktionszugangsdaten (beginnen mit APP_USR-): jeweils einen Public Key und einen Access Token. Für die optionale Signaturprüfung der Benachrichtigungen benötigen Sie außerdem das geheime Signaturgeheimnis aus your application > Webhooks.

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

Installation

1. Gehen Sie in WordPress zu Plugins > Add New > Upload Plugin, wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Install Now. Sie können auch den Ordner wcp_mercadopago_gateway per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

3. Öffnen Sie die Einstellungen: WooCommerce > Settings > Payments > MercadoPago > Manage oder klicken Sie auf der Seite Plugins unter dem Plugin-Namen auf Settings.

4. Geben Sie Ihren VibeFox-Lizenzschlüssel im Lizenzblock oben auf der Seite ein und klicken Sie auf Activate.

5. Wählen Sie das Account country, geben Sie die Test- und Produktionszugangsdaten ein und richten Sie optional die Benachrichtigungen in Ihrer MercadoPago-Anwendung ein (siehe Konfiguration).

6. Schalten Sie Enable / Disable ein und speichern Sie. Testen Sie mit MercadoPago-Testkarten (Name des Karteninhabers APRO = genehmigt, CONT = ausstehend, OTHE = abgelehnt) und deaktivieren Sie danach Test mode.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > MercadoPago. Über den Feldern zeigt die Seite Test mode is on: the TEST- credentials are used and no real money is charged., solange der Testmodus aktiv ist. Sie warnt, wenn die Zugangsdaten des aktuellen Modus fehlen oder die Shopwährung nicht die Währung Ihres MercadoPago-Kontos ist (dann wird die Zahlungsmethode an der Kasse ausgeblendet), und wenn die Zugangsdaten zu einem Konto in einem anderen Land als Account country gehören. In der Liste der Zahlungsmethoden ist MercadoPago als einrichtungsbedürftig markiert, bis der aktuelle Modus seine Zugangsdaten hat.

Beim Speichern wird ein Zugangsdatum, das nicht mit dem erwarteten Präfix beginnt (TEST- für Testfelder, APP_USR- für Produktionsfelder), nicht gespeichert: Es erscheint eine Fehlermeldung und der vorherige Wert bleibt erhalten. Das Plugin fragt außerdem bei MercadoPago ab, zu welchem Land der Access Token gehört. Kann es das Token nicht prüfen, liegt das Konto nicht in einem unterstützten Land oder weicht das Land von Account country ab, erscheint ein Fehler. Das Plugin verwendet dann das Land des Kontos.

General

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

Title: der Name der Zahlungsmethode, den der Kunde an der Kasse sieht. Standard: Credit or debit card (MercadoPago).

Description: der Text über den Kartenfeldern an der Kasse. Standard: Pay securely with your credit or debit card. Card data is sent directly to MercadoPago.

MercadoPago-Konto

Holen Sie die Zugangsdaten Ihrer Anwendung im MercadoPago-Entwicklerportal: Your integrations > your application > Credentials. Testzugangsdaten beginnen mit TEST-, Produktionszugangsdaten mit APP_USR-.

Account country: das Land Ihres MercadoPago-Kontos. Es bestimmt die Belastungswährung, die Sprache der Kartenfelder und ob das Ausweisdokument abgefragt wird. Die Shopwährung muss dieselbe sein, zum Beispiel ARS für Argentinien. Standard: Argentina (ARS).

Argentina (ARS), Brazil (BRL), Chile (CLP), Colombia (COP), Mexico (MXN), Peru (PEN), Uruguay (UYU): die unterstützten Länder. Das Dokumentfeld wird für alle außer Mexiko angezeigt.

Test mode: Use the test credentials (no real charges). Im Testmodus werden die TEST-Zugangsdaten verwendet und Sie zahlen mit MercadoPago-Testkarten; an der Kasse erscheint das Abzeichen TEST MODE. Deaktivieren Sie das Feld, um echte Karten mit den Produktionszugangsdaten zu belasten. Standard: ein. Um mit einem MercadoPago-Testnutzerkonto (APP_USR-Zugangsdaten) zu testen, geben Sie die Zugangsdaten dieses Kontos in die Produktionsfelder ein und deaktivieren Sie den Testmodus.

Test Public Key: beginnt mit TEST-. Wird im Browser zur Tokenisierung der Karte verwendet.

Test Access Token: beginnt mit TEST-. Wird nur auf dem Server verwendet. Geheim halten.

Production Public Key: beginnt mit APP_USR-.

Production Access Token: beginnt mit APP_USR-. Wird nur auf dem Server verwendet. Geheim halten.

Zahlungsoptionen

Maximum installments: die höchste Anzahl Raten, die der Kunde wählen kann, von 1 bis 24. 1 = nur Einmalzahlung, dann wird das Ratenfeld nicht angezeigt. Die Grenze wird auch auf dem Server erzwungen. Standard: 1.

Zahlungsbenachrichtigungen (Webhooks)

Kartenzahlungen erhalten meist sofort eine endgültige Antwort. Zahlungen, die MercadoPago in Prüfung hält (in Bearbeitung oder ausstehend), werden durch Benachrichtigungen von MercadoPago abgeschlossen. Das Plugin sendet die Benachrichtigungs-URL bei jeder Zahlung, wenn Ihre Website eine öffentliche Adresse hat. Sie können sie auch in your application > Webhooks hinzufügen, Ereignis Payments. Die URL wird in diesem Abschnitt der Einstellungen angezeigt und sieht so aus: https://your-site/wc-api/wc_mpg_webhook/?source_news=webhooks.

Einer Benachrichtigung wird nie einfach vertraut. Das Plugin ruft die Zahlung erneut über die MercadoPago-API ab, mit dem Access Token der Umgebung, in der die Zahlung erfolgte, und ordnet sie der Bestellung über Bestell-ID und Bestellschlüssel zu. Ohne Benachrichtigungen bleiben Bestellungen in Prüfung auf In Wartestellung, bis Sie sie manuell aktualisieren.

Das Plugin verarbeitet diese MercadoPago-Zahlungsstatus:

approved: die Zahlung wurde genehmigt. Die Bestellung wird als bezahlt markiert, wenn Betrag und Währung übereinstimmen.

in_process, pending, authorized: die Zahlung wird geprüft. Die Bestellung wird auf In Wartestellung gesetzt und durch eine spätere Benachrichtigung abgeschlossen.

rejected, cancelled: die Zahlung wurde abgelehnt oder storniert. Eine unbezahlte Bestellung wird als Fehlgeschlagen markiert.

refunded, charged_back, in_mediation: es wird eine Notiz hinzugefügt; der Bestellstatus ändert sich nicht.

Webhook secret signature: optional. Die geheime Signatur, die unter your application > Webhooks angezeigt wird. Ist sie gesetzt, werden Benachrichtigungen ohne gültige x-signature abgelehnt (HTTP 401).

Erweitert

Debug log: Log API requests and notifications schreibt in WooCommerce > Status > Logs, Quelle wcp_mercadopago_gateway. Access Tokens, Karten-Tokens und Zahlerdaten werden nicht protokolliert. Standard: aus.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. MercadoPago-Zahlungs-IDs an Bestellungen sind Zahlungshistorie und bleiben immer erhalten. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Credit or debit card (MercadoPago)) und füllt die Kartenfelder aus: Card number, Expiry (MM/YY), Security code und Cardholder name. Je nach Land und Karte wählt der Kunde außerdem Document type und gibt Document number ein, wählt den Card issuer und die Anzahl der Installments. Die Ratenoptionen und Zinsen stammen von MercadoPago für den Bestellbetrag.

Beim Abschluss der Bestellung wandelt MercadoPago die Karte in ein Einmal-Token um, und Ihr Shop erstellt die Zahlung auf dem Server für den Bestellbetrag. E-Mail-Adresse und Name der Rechnung, das Dokument und die Bestellnummer werden an MercadoPago übergeben. Beträge in CLP und COP werden ohne Dezimalstellen auf ganze Zahlen gerundet belastet. Setzen Sie deshalb für diese Währungen die Anzahl der Dezimalstellen in WooCommerce auf 0.

Eine genehmigte Zahlung wird sofort als bezahlt markiert, und der Kunde gelangt zur Seite „Bestellung eingegangen“. Eine Zahlung in Prüfung setzt die Bestellung auf In Wartestellung; der Kunde gelangt ebenfalls zur Seite „Bestellung eingegangen“, und die Benachrichtigung schließt die Bestellung ab. Eine abgelehnte Karte zeigt an der Kasse einen kurzen Grund, zum Beispiel Your card has insufficient funds. Please use another card or payment method. oder Please check the security code of your card. Der Kunde kann die Daten korrigieren oder eine andere Karte verwenden; für jeden Versuch wird ein neues Karten-Token erstellt.

Antwortet MercadoPago nicht, sieht der Kunde We could not confirm your payment with MercadoPago. Please wait a minute before trying again — if the payment went through, your order will be updated automatically. Der nächste Versuch sucht zuerst nach der Zahlung, damit die Karte nicht doppelt belastet wird. Ein zweiter Klick, während die Bestellung bezahlt wird, zeigt This order is already being paid. Please wait a moment and check your e-mail before trying again.

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

Das Plugin akzeptiert nur Kredit- und Debitkarten. Es gibt keine Weiterleitung zu Checkout Pro, keine MercadoPago-Wallet oder Kontoguthaben, keine Barzahlung (Rapipago, OXXO, Boleto und andere), kein Pix, PSE oder Yape, keine gespeicherten Karten oder Abonnements, kein getrenntes Autorisieren und Erfassen, keine 3-D-Secure-Abfrage und keine Währungsumrechnung.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: die Bestellung wurde angelegt, und noch ist kein Zahlungsergebnis eingegangen, zum Beispiel nach einem Timeout.

Processing: MercadoPago hat die Zahlung genehmigt, und Betrag und Währung stimmen überein. Bestellungen mit ausschließlich virtuellen, herunterladbaren Produkten werden auf Abgeschlossen gesetzt, wie es WooCommerce standardmäßig tut. Die Bestellnotiz zeigt die MercadoPago-Zahlungs-ID und die Anzahl der Raten. Die Transaktions-ID ist die MercadoPago-Zahlungs-ID.

On hold: die Zahlung wird geprüft (in Bearbeitung oder ausstehend) und wartet auf die Benachrichtigung von MercadoPago. In Wartestellung wird die Bestellung auch gesetzt, wenn der genehmigte Betrag oder die Währung nicht zur Bestellung passt oder MercadoPago einen unerwarteten Status zurückgibt. Die Bestellnotiz erklärt es.

Failed: die Zahlung wurde abgelehnt oder storniert. Die Bestellnotiz zeigt den Status und dessen Details. Der Kunde kann erneut bezahlen.

Genehmigt MercadoPago eine Zahlung für eine stornierte oder erstattete Bestellung, ändert sich der Status nicht, und eine Notiz fordert Sie auf, die Bestellung abzuschließen oder die Zahlung zu erstatten. Geht eine weitere Zahlung für eine bereits bezahlte Bestellung ein, fordert Sie eine Notiz auf, die zusätzliche Zahlung im MercadoPago-Portal zu erstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Credit or debit card (MercadoPago) (die Schaltfläche zeigt Ihren Title). Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird mit den Zugangsdaten der Umgebung gesendet, in der die Zahlung erfolgte (Test oder Produktion), daher muss deren Access Token gesetzt sein. Lehnt MercadoPago die Erstattung ab, zeigt WooCommerce MercadoPago refused the refund mit dem Grund an, und es wird keine Erstattung erfasst. Eine genehmigte oder in Bearbeitung befindliche Erstattung wird mit der Erstattungs-ID zu den Bestellnotizen hinzugefügt.

Erstattungen und Chargebacks, die im MercadoPago-Portal vorgenommen werden, kommen über die Benachrichtigung und werden den Bestellnotizen hinzugefügt. Sie werden nicht automatisch als WooCommerce-Erstattungen erfasst.

Lizenzschlüssel

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

Ein Schlüssel funktioniert 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 MercadoPago Kunden an der Kasse nicht angezeigt. Wird trotzdem eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shopverwalter sehen die Zahlungsmethode weiterhin, markiert mit (unlicensed — visible to admins only), damit Sie das Plugin einrichten und testen können, bevor Sie einen Schlüssel kaufen. Eine Erinnerung erscheint auf der Seite Plugins und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: bereits gestartete Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

Läuft eine Lizenz ab, arbeitet das Plugin weiter, doch Updates und Support erfordern eine Verlängerung. Der Status wird automatisch im Hintergrund erneut geprüft.

Fehlerbehebung

MercadoPago does not appear at checkout: prüfen Sie, dass die Lizenz aktiv ist, Enable / Disable eingeschaltet ist und der aktuelle Modus beide Zugangsdaten mit dem richtigen Präfix hat: die TEST-Schlüssel im Testmodus, die APP_USR-Schlüssel im Produktivbetrieb. Prüfen Sie, dass die Shopwährung (bzw. die Bestellwährung auf der Seite Pay for order) die Währung Ihres MercadoPago-Kontos ist. Die Einstellungsseite zeigt an, welche Angabe fehlt.

The payment went through, but the order stays In Wartestellung or Zahlung ausstehend: die Benachrichtigung ist nicht angekommen. Das Plugin sendet die Benachrichtigungs-URL nur, wenn Ihre Website eine öffentliche Adresse hat (nicht localhost und keine Domain mit .local oder .test). Fügen Sie die URL aus den Einstellungen in your application > Webhooks mit dem Ereignis Payments hinzu. Ist Webhook secret signature gesetzt, prüfen Sie, ob es das Geheimnis derselben Anwendung ist. Das MercadoPago-Portal zeigt für jede Benachrichtigung die Antwort Ihres Shops.

Notification answers invalid signature: das Geheimnis gehört zu einer anderen Anwendung, oder die Benachrichtigung hat keine gültige x-signature. Kopieren Sie das Geheimnis erneut oder lassen Sie das Feld leer.

Notification answers not for this store: die Zahlung gehört nicht zu einer Bestellung dieses Shops, die mit MercadoPago bezahlt wurde. Die Bestellung wird nicht verändert.

A credential is not saved: die Meldung must start with zeigt, dass der Wert das falsche Präfix für das Feld hat. Testfelder akzeptieren TEST-Zugangsdaten, Produktionsfelder APP_USR-Zugangsdaten.

The customer sees This payment method is not configured correctly. Please choose another payment method or contact the store.: die Zugangsdaten des aktuellen Modus fehlen, haben das falsche Präfix oder wurden von MercadoPago abgelehnt. Prüfen Sie sie auf der Einstellungsseite.

The customer sees MercadoPago cannot process payments in: die Bestellwährung ist nicht die Währung Ihres MercadoPago-Kontos. MercadoPago rechnet keine Währungen um.

The secure card form does not load: der Kunde sieht The secure card form could not be loaded. Please reload the page or choose another payment method. Prüfen Sie den Public Key des aktuellen Modus. Für weitere Details aktivieren Sie das Debug log und sehen unter WooCommerce > Status > Logs, Quelle wcp_mercadopago_gateway, nach.

Refund fails with a message about the mode: die Zahlung wurde im Test- oder Produktionsmodus gemacht, und der Access Token dieses Modus ist nicht gesetzt. Tragen Sie ihn ein und versuchen Sie es erneut.

Refund fails with MercadoPago did not answer the refund request: prüfen Sie die Zahlung im MercadoPago-Portal, bevor Sie es erneut versuchen.

The license block shows an error: folgen Sie der Meldung im Block. Ist der Schlüssel zum Beispiel bereits auf einer anderen Domain verwendet, geben Sie in Ihrem vibefox.net-Konto einen Platz frei und klicken Sie auf Check now. Hat sich die Adresse der Website 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.

Deinstallation

Das Deaktivieren des Plugins behält alle Daten. Zum Entfernen deaktivieren und löschen Sie es auf der Seite Plugins. Lizenzschlüssel und Lizenzstatus dieses Plugins werden immer entfernt. Die Gateway-Einstellungen, die gespeicherte Kontoprüfung und die Protokolle werden nur entfernt, wenn Delete data on uninstall aktiv war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, MercadoPago-Zahlungs-IDs und Transaktions-IDs.

MercadoPago ist eine Marke ihres jeweiligen Inhabers. Dieses Plugin ist nicht mit MercadoPago verbunden und wird von MercadoPago nicht empfohlen.