VibeFox MercadoPago for PrestaShop — Hilfe

Anforderungen

PrestaShop: 8.0 bis 9.x.

PHP: 8.0 oder neuer. Das Modul verweigert die Installation auf älteren PHP-Versionen.

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, daher wird die Zahlungsart bei einem Warenkorb in einer anderen Währung ausgeblendet.

MercadoPago-Konto: Sie brauchen 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 ein Access Token. Für die optionale Signaturprüfung der Benachrichtigungen brauchen Sie außerdem den geheimen Signaturschlüssel aus your application > Webhooks.

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.

2. Wenn der Upload abgeschlossen ist, klicken Sie auf Configure, oder suchen Sie später in der Modulliste nach VibeFox MercadoPago Gateway 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. 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).

5. Aktivieren Sie Enable / Disable und klicken Sie auf Save. Testen Sie eine Zahlung im Testmodus mit MercadoPago-Testkarten und schalten Sie danach Test mode aus.

Bei der Installation legt das Modul zwei Bestellstatus an: Awaiting MercadoPago payment und MercadoPago payment on hold. PrestaShop weist einem neuen Zahlungsmodul die Länder zu, die zum Zeitpunkt der Installation aktiv sind. Prüfen Sie die Währungen, Länder und Kundengruppen des Moduls unter Payment > Preferences.

Konfiguration

Alle Einstellungen befinden sich auf der Modulseite: Modules > Module Manager > VibeFox MercadoPago Gateway > Configure. Jeder Abschnitt hat seine eigene Schaltfläche Save, die die gesamte Seite speichert. Ü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 außerdem, wenn der Public Key oder das Access Token des aktuellen Modus fehlt, wenn die Shopwährung nicht die Währung Ihres MercadoPago-Kontos ist (dann wird die Zahlungsart an der Kasse ausgeblendet) und wenn die Zugangsdaten zu einem Konto in einem anderen Land gehören als Account country.

Beim Speichern wird ein Zugangsdatum, das nicht mit dem erwarteten Präfix beginnt (TEST- für die Testfelder, APP_USR- für die Produktionsfelder), nicht gespeichert; es erscheint der Fehler must start with … — the previous value was kept.. Das Modul fragt außerdem bei MercadoPago ab, zu welchem Land jedes Access Token gehört. Kann das Token des aktuellen Modus nicht geprüft werden, liegt das Konto in keinem unterstützten Land oder stimmt das Land nicht mit Account country überein, wird ein Fehler angezeigt. Das Modul verwendet dann das Land des Kontos.

MercadoPago

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

Title: der Name der Zahlungsart, den der Kunde an der Kasse sieht. Er wird auch als Name der Zahlungsart in der Bestellung gespeichert. Standard: Credit or debit card (MercadoPago). Pflichtfeld.

Description: der Text, der an der Kasse über den Kartenfeldern angezeigt wird. 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. Beim Speichern der Zugangsdaten wird das Land mit dem Konto abgeglichen. Standard: Argentina (ARS).

Test mode: Im Testmodus werden die TEST-Zugangsdaten verwendet, und Sie zahlen mit MercadoPago-Testkarten; an der Kasse wird das Kennzeichen TEST MODE angezeigt. Schalten Sie den Modus aus, um echte Karten mit den Produktionszugangsdaten zu belasten. Standard: on.

Test Public Key: beginnt mit TEST-. Wird im Browser verwendet, um die Karte zu tokenisieren.

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.

Gespeicherte Access Tokens und das Webhook-Secret werden nicht erneut 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.

Zahlungsoptionen

Maximum installments: die höchste Anzahl an Raten, die der Kunde wählen kann, von 1 bis 24. 1 = nur Einmalzahlung, dann wird kein Ratenfeld angezeigt. Das Limit wird auch auf dem Server geprüft. 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 MercadoPago-Benachrichtigungen abgeschlossen. Das Modul sendet die Benachrichtigungs-URL bei jeder Zahlung, wenn Ihr Shop eine öffentliche Adresse hat (nicht localhost oder eine Domain mit .local oder .test). Sie können sie auch in your application > Webhooks hinzufügen, Ereignis Payments. Die URL wird in diesem Abschnitt unter Notification URL angezeigt. Mit freundlichen URLs sieht sie so aus: https://your-shop/en/module/wcp_mercadopago_gateway/webhook?source_news=webhooks. Kopieren Sie die URL genau so, wie die Einstellungen sie anzeigen.

Einer Benachrichtigung wird nie ungeprüft vertraut. Das Modul liest die Zahlung mit dem Access Token der Umgebung, in der sie erfolgt ist, erneut über die MercadoPago-API aus und ordnet sie einem Zahlungsversuch Ihres Shops zu. Ohne Benachrichtigungen bleiben Bestellungen in Prüfung auf Awaiting MercadoPago payment, bis Sie sie manuell aktualisieren.

Das Modul verarbeitet diese MercadoPago-Zahlungsstatus:

Webhook secret signature: optional. Der geheime Signaturschlüssel, der unter your application > Webhooks angezeigt wird. Ist er gesetzt, werden Benachrichtigungen ohne gültige x-signature abgelehnt (HTTP 401).

Clear saved secrets: Haken Sie Test Access Token, Production Access Token oder Webhook secret signature an und klicken Sie auf Save, um ihn zu entfernen. Ein leeres Feld behält den gespeicherten Wert.

Erweitert

Debug log: schreibt MercadoPago-Anfragen und -Benachrichtigungen in logs/wc_mpg_debug.log.php im Modulordner. Die Datei kann nicht über das Web geöffnet werden. Fehler werden immer protokolliert, auch wenn diese Einstellung aus ist. Access Tokens, Kartentokens und Zahlerdaten werden nicht protokolliert. Standard: off.

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 sie aktiv, entfernt die Deinstallation des Moduls die Gateway-Einstellungen und die Protokolle. MercadoPago-Zahlungsdatensätze, Erstattungen und die Bestellstatus des Moduls bleiben immer erhalten, sodass früher bezahlte Bestellungen auch nach einer Neuinstallation erstattet werden können. Standard: off.

Kasse

Im Zahlungsschritt wählt der Kunde die Zahlungsart (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 die Document number ein, wählt den Card issuer und die Anzahl der Installments. Die Ratenoptionen und Zinsen kommen von MercadoPago für den Warenkorbbetrag. Das Kartenformular funktioniert mit den Themes Classic und Hummingbird.

Wenn der Kunde bestätigt, wandelt MercadoPago die Karte in ein Einmal-Token um, und Ihr Shop erstellt die Zahlung auf dem Server für den Warenkorbbetrag. E-Mail-Adresse und Name des Kunden, das Dokument und die Warenkorbnummer werden an MercadoPago übergeben; die Zahlung erscheint als Cart #, mit der Warenkorbnummer und dem Namen Ihres Shops. Beträge in CLP und COP werden ohne Dezimalstellen belastet. Vor der Antwort von MercadoPago existiert keine Bestellung.

Eine genehmigte Zahlung erstellt eine bezahlte Bestellung, und der Kunde sieht die Bestellbestätigungsseite mit Your card payment has been received. Eine Zahlung in Prüfung erstellt eine Bestellung auf Awaiting MercadoPago payment, und die Seite zeigt MercadoPago is reviewing your payment. Your order will be updated automatically as soon as MercadoPago confirms it. Wird eine Zahlung in Prüfung später abgelehnt, zeigt die Seite Your MercadoPago payment was not completed. Please contact us about this order. Eine zurückgehaltene Bestellung zeigt Your payment is being reviewed. We will update your order as soon as the review is complete.

Eine abgelehnte Karte erstellt keine Bestellung. Der Kunde bleibt im Zahlungsschritt mit einem 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; bei jedem Versuch wird ein neues Kartentoken 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, sodass die Karte nicht doppelt belastet wird. Ein zweiter Klick, während der Warenkorb bezahlt wird, zeigt This order is already being paid. Please wait a moment and check your e-mail before trying again. Ein Warenkorb mit bereits vorhandener Bestellung wird nie erneut belastet; der Kunde wird zur Bestätigungsseite dieser Bestellung geleitet.

Die Benachrichtigungs-URL funktioniert auch im Wartungsmodus des Shops und wird nicht durch die Ländereinschränkung Ihres Shops blockiert.

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

No order: die Karte wurde abgelehnt, oder MercadoPago hat noch nicht geantwortet. Es existiert nur der Warenkorb.

Payment accepted: MercadoPago hat die Zahlung genehmigt, und Betrag und Währung stimmen mit dem Warenkorb überein. Die Zahlung wird mit der MercadoPago-Zahlungs-ID als Transaktions-ID erfasst, und eine Notiz zeigt die Zahlungs-ID, die Umgebung und die Anzahl der Raten.

Awaiting MercadoPago payment: die Zahlung wird geprüft (in Bearbeitung oder ausstehend) und wartet auf die MercadoPago-Benachrichtigung. Die Bestellung wechselt zu Payment accepted, sobald MercadoPago sie genehmigt.

MercadoPago payment on hold: der genehmigte Betrag oder die Währung weicht vom Warenkorb ab, oder MercadoPago hat einen unerwarteten Status zurückgegeben. Die Notiz erklärt es. Prüfen Sie die Bestellung und erfüllen Sie sie oder erstatten Sie die Zahlung.

Payment error: eine Zahlung in Prüfung wurde abgelehnt oder storniert. Die Notiz zeigt den Status und seine Einzelheiten.

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

Genehmigt MercadoPago eine Zahlung für eine bereits stornierte oder erstattete Bestellung, bleibt der Status unverändert, und eine Notiz bittet Sie, die Bestellung abzuschließen oder die Zahlung zu erstatten. Kommt eine weitere Zahlung für eine bereits bezahlte Bestellung an, bittet Sie eine Notiz, die zusätzliche Zahlung im MercadoPago-Panel zu erstatten.

Block „MercadoPago-Zahlung“

Die Bestellseite zeigt einen Block MercadoPago payment mit der Zahlungs-ID, dem Zahlungsstatus, der Umgebung (ein Kennzeichen Test bei Testzahlungen), den Raten, dem von MercadoPago belasteten Betrag und der Bestellsumme, dem erstatteten Betrag, dem Erstattungsverlauf und den MercadoPago notes der Bestellung.

Erstattungen

Geben Sie im Block MercadoPago payment den Betrag ein (der noch nicht erstattete Betrag ist vorausgefüllt), optional einen Grund, und klicken Sie auf Refund via MercadoPago. Bestätigen Sie die Frage Refund this amount through MercadoPago? This cannot be undone. Vollständige und teilweise Erstattungen werden unterstützt. Sie benötigen das Recht, Bestellungen zu bearbeiten. Erstattungen sind auf den von MercadoPago belasteten Betrag begrenzt; nach einer Betragsabweichung können Sie daher bis zu dem erstatten, was der Kunde tatsächlich bezahlt hat, nicht bis zur Bestellsumme. Die Erstattung wird mit den Zugangsdaten der Umgebung gesendet, in der die Zahlung erfolgte (Test oder Produktion), daher muss das Access Token dieser Umgebung gesetzt sein. Lehnt MercadoPago die Erstattung ab, zeigt der Block MercadoPago refused the refund mit dem Grund an, und es wird keine Erstattung erfasst. Eine genehmigte oder in Bearbeitung befindliche Erstattung wird mit ihrer Erstattungs-ID dem Erstattungsverlauf und den Notizen hinzugefügt. Eine vollständige Erstattung setzt die Bestellung auf Refunded. Eine teilweise Erstattung ändert den Status nicht.

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

Erstattungen, Rückbuchungen und Schlichtungen, die im MercadoPago-Panel vorgenommen werden, kommen über die Benachrichtigung an und werden den Notizen hinzugefügt. Bestellstatus und Gutschriften werden nicht automatisch geändert. Aktualisieren Sie sie bei Bedarf manuell.

Lizenzschlüssel

Das Modul funktioniert mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock License — VibeFox MercadoPago Gateway ist der erste Block unter Modules > Module Manager > VibeFox MercadoPago 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-mercadopago 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 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. 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 an der Kasse nicht testen. Eine Erinnerung erscheint unter Modules > Module Manager auf dem Tab Alerts. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene 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

MercadoPago erscheint nicht an der Kasse: Prüfen Sie, ob 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 in der Produktion. Prüfen Sie, dass die Warenkorbwährung die Währung Ihres MercadoPago-Kontos ist. Die Einstellungsseite zeigt an, was fehlt. 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 die Bestellung bleibt auf Awaiting MercadoPago payment: die Benachrichtigung ist nicht angekommen. Das Modul sendet die Benachrichtigungs-URL nur, wenn Ihr Shop eine öffentliche Adresse hat (nicht localhost oder eine Domain mit .local oder .test). Fügen Sie die URL aus Notification URL unter 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-Panel zeigt für jede Benachrichtigung die Antwort Ihres Shops.

Die Benachrichtigung antwortet invalid signature: das Signaturgeheimnis 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.

Die Benachrichtigung antwortet no credentials for test or no credentials for live: das Access Token der Umgebung, in der die Zahlung erfolgte, ist nicht gesetzt. Geben Sie es ein; MercadoPago wiederholt die Benachrichtigung.

Die Benachrichtigung antwortet not for this store: die Zahlung gehört zu keinem Zahlungsversuch dieses Shops. Es wird keine Bestellung geändert.

Die Benachrichtigung antwortet order busy or payment could not be read: die Bestellung wurde im selben Moment von einer anderen Anfrage aktualisiert, oder MercadoPago war nicht erreichbar. MercadoPago wiederholt die Benachrichtigung automatisch.

Ein Zugangsdatum wird nicht gespeichert: der Fehler must start with zeigt, dass der Wert für dieses Feld das falsche Präfix hat. Testfelder akzeptieren TEST-Zugangsdaten, Produktionsfelder APP_USR-Zugangsdaten.

Der Kunde sieht 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.

Der Kunde sieht MercadoPago cannot process payments in: die Warenkorbwährung ist nicht die Währung Ihres MercadoPago-Kontos. MercadoPago rechnet keine Währungen um.

Das sichere Kartenformular lädt nicht: 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.

Der Kunde sieht Your payment was received, but the order could not be completed automatically: MercadoPago hat die Zahlung eingezogen, aber PrestaShop konnte die Bestellung nicht anlegen (zum Beispiel weil das Modul in diesem Moment deaktiviert war). Sehen Sie im Feld Log der Modulseite nach: Fehler werden immer protokolliert. Der Kunde wird gebeten, nicht erneut zu zahlen; der nächste Zahlungsversuch oder die nächste Benachrichtigung für den Warenkorb legt die Bestellung ohne erneute Belastung an.

Die Bestellung steht nach der Zahlung auf MercadoPago payment on hold: lesen Sie die MercadoPago notes im Bestellblock (siehe Bestellstatus) und erfüllen Sie dann die Bestellung oder erstatten Sie die Zahlung.

Die Erstattung schlägt mit einer Meldung zum Modus fehl: die Zahlung erfolgte im Test- oder Produktionsmodus, und das Access Token dieses Modus ist nicht gesetzt. Geben Sie es ein und versuchen Sie es erneut.

Die Erstattung schlägt fehl, MercadoPago did not answer the refund request: prüfen Sie die Zahlung im MercadoPago-Panel, bevor Sie es erneut versuchen.

Deinstallation

Gehen Sie zu Modules > Module Manager, öffnen Sie das Menü neben VibeFox MercadoPago 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, die gespeicherte Kontoprüfung und die Protokolle entfernt. Ist es aus, bleiben alle Einstellungen für eine spätere Neuinstallation erhalten. Die MercadoPago-Zahlungsdatensätze und Erstattungen sowie die Bestellstatus Awaiting MercadoPago payment und MercadoPago 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.

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