VibeFox Przelewy24 for WooCommerce — Hilfe

Anforderungen

WordPress: 5.8 oder neuer.

WooCommerce: 7.0 oder neuer, installiert und aktiv. Das Plugin lässt sich ohne WooCommerce nicht aktivieren.

PHP: 8.0 oder neuer.

Währung: Die Bestellung muss in PLN, EUR, GBP oder CZK erfolgen. In anderen Währungen wird die Zahlungsmethode an der Kasse ausgeblendet. Die Bestellung wird in ihrer eigenen Währung belastet; das Plugin rechnet keine Währungen um.

Przelewy24-Konto: Sie benötigen ein Przelewy24-Händlerkonto und dessen API-Daten: die Merchant ID, den API-Schlüssel (im Przelewy24-Panel als report key bezeichnet), den CRC-Schlüssel und, falls Ihr Shop eine eigene ID hat, die POS ID (Shop ID). Sie finden sie im Händlerpanel von Przelewy24 unter panel.przelewy24.pl unter My data > API data and configuration. Sandbox-Schlüssel stammen aus einem separaten Sandbox-Konto unter sandbox.przelewy24.pl/panel. Im Przelewy24-Panel ist sonst nichts einzurichten: Das Plugin übermittelt bei jeder Zahlung seine Benachrichtigungs-URL. Ihre Website muss aus dem Internet erreichbar sein, da Przelewy24 dorthin die Zahlungsbenachrichtigungen sendet.

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. Alternativ können Sie den Ordner wcp_przelewy24_payment per FTP nach /wp-content/plugins/ hochladen.

2. Klicken Sie auf Activate.

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

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

5. Geben Sie die Sandbox-Schlüssel ein (Merchant ID, API key, CRC key; die POS ID nur, falls sie von der Merchant ID abweicht), aktivieren Sie Enable/Disable, speichern Sie und führen Sie eine Testzahlung im Sandbox-Modus durch.

6. Geben Sie die Live-Schlüssel ein, entfernen Sie den Haken bei Test Mode und speichern Sie, um echte Zahlungen anzunehmen.

Konfiguration

Alle Einstellungen befinden sich auf einer Seite: WooCommerce > Settings > Payments > Przelewy24. Oberhalb der Felder zeigt die Seite Warnungen an, wenn etwas fehlt. Solange die Sandbox aktiv ist: Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. Wenn die Schlüssel des aktuellen Modus unvollständig sind: Enter the Sandbox Merchant ID, API key and CRC key — until then Przelewy24 is not shown at checkout. (bzw. dasselbe für die Live-Schlüssel). Akzeptiert Przelewy24 die Shop-Währung nicht, nennt die Warnung die Währung und die unterstützten Währungen. Nach dem Speichern folgen die Warnungen sofort dem neuen Modus und den neuen Schlüsseln. Leerzeichen und Zeilenumbrüche, die beim Kopieren der Schlüssel aus dem Przelewy24-Panel mitkopiert wurden, werden beim Speichern entfernt.

Kasse

Enable/Disable: Enable Przelewy24 Payment schaltet die Zahlungsmethode ein oder aus. Standard: aus.

Title: der Name der Zahlungsmethode, den Kunden an der Kasse sehen. Standard: Przelewy24.

Description: der Text, der an der Kasse unter der Zahlungsmethode angezeigt wird. Standard: Pay with BLIK, online bank transfer or card via Przelewy24.

API-Zugangsdaten

Dieser Abschnitt erklärt, wo Sie die Schlüssel finden (My data > API data and configuration im Händlerpanel von Przelewy24), und verlinkt auf panel.przelewy24.pl und sandbox.przelewy24.pl/panel.

Test Mode: Enable sandbox (test) mode. Ist sie aktiv, gehen neue Zahlungen mit den Sandbox-Schlüsseln an die Przelewy24-Sandbox (sandbox.przelewy24.pl), und es wird kein echtes Geld belastet. Entfernen Sie den Haken, um echte Zahlungen auf secure.przelewy24.pl mit den Live-Schlüsseln anzunehmen. Standard: aktiv.

Live-Schlüssel

Live Merchant ID: Ihre Przelewy24-Händler-ID, nur Ziffern.

Live POS ID (optional): die Shop ID (posId). Leer lassen, wenn sie mit der Merchant ID identisch ist.

Live API key (report key): der API-Schlüssel aus dem Przelewy24-Panel. Er dient der API-Authentifizierung zusammen mit der POS ID.

Live CRC key: dient dazu, Anfragen an Przelewy24 zu signieren und die Signatur von Przelewy24-Benachrichtigungen zu prüfen.

Sandbox-Schlüssel

Sandbox Merchant ID: die Merchant ID Ihres Przelewy24-Sandbox-Kontos.

Sandbox POS ID (optional): die Shop ID (posId) des Sandbox-Kontos. Leer lassen, wenn sie mit der Merchant ID identisch ist.

Sandbox API key (report key): der API-Schlüssel des Sandbox-Kontos.

Sandbox CRC key: der CRC-Schlüssel des Sandbox-Kontos, der zum Signieren von Anfragen und zum Prüfen von Sandbox-Benachrichtigungen dient.

Live- und Sandbox-Schlüssel sind verschieden. Merchant ID und POS ID dürfen nur Ziffern enthalten; solange Merchant ID, API key und CRC key des aktuellen Modus nicht eingegeben sind, wird die Zahlungsmethode an der Kasse nicht angezeigt. Eine in einem Modus gestartete Zahlung wird immer mit den Schlüsseln dieses Modus verifiziert und erstattet, auch nach dem Umschalten. Bewahren Sie deshalb die Schlüssel des alten Modus auf, solange dessen Zahlungen noch offen sind oder erstattet werden könnten.

Zahlungsbenachrichtigungen

Dieser Abschnitt zeigt die Benachrichtigungs-URL Ihres Shops. Sie sieht etwa so aus: https://your-site/wc-api/wc_p24_payment/. Das Plugin übermittelt diese URL bei jeder Zahlung an Przelewy24, daher muss im Przelewy24-Panel nichts konfiguriert werden. Über dieselbe URL kommen auch die Erstattungsergebnisse an. Die URL muss aus dem Internet erreichbar sein: keine Firewall, kein Wartungsmodus und keine HTTP-Authentifizierung davor. Ohne Benachrichtigungen wird eine Zahlung bestätigt, sobald der Kunde zur Seite „Bestellung eingegangen“ zurückkehrt (siehe Kasse); kehrt der Kunde nicht zurück, bleibt die Bestellung auf „Pending payment“.

Erweitert

Debug Log: Enable logging schreibt technische Ereignisse (Bestellnummern, P24-Transaktions-IDs, Fehler) nach WooCommerce > Status > Logs, Quelle wcp_przelewy24_payment. Fehler und Warnungen werden immer protokolliert. Schlüssel, Anfragetexte und personenbezogene Daten werden nie protokolliert. Standard: aus.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Bestellungen und ihre Zahlungsdaten werden nie gelöscht. Das Deaktivieren des Plugins behält alles. Standard: aus.

Kasse

Der Kunde wählt die Zahlungsmethode (standardmäßig Przelewy24, mit dem P24-Logo im Kassen-Block) und gibt die Bestellung auf. Im Sandbox-Modus zeigt der Kassen-Block Sandbox mode — no real money is charged an. Das Plugin legt für die Bestellung eine Przelewy24-Transaktion über den Bestellbetrag in der Bestellwährung an, mit E-Mail-Adresse, Name und Rechnungsland des Kunden, und fügt der Bestellung eine Notiz mit der Session-ID und dem Modus (Sandbox oder Live) hinzu. Jeder Zahlungsversuch erhält eine eigene Session-ID. Der Kunde wird zur Zahlungsseite von Przelewy24 weitergeleitet und zahlt mit BLIK, einer Online-Banküberweisung, einer Karte oder einer anderen für Ihr Przelewy24-Konto aktivierten Methode. Die Zahlungsseite wird in der Sprache der Website angezeigt, sofern Przelewy24 sie unterstützt, andernfalls auf Englisch.

Die Bestellung wird erst als bezahlt markiert, wenn Przelewy24 die Zahlung bestätigt. Przelewy24 sendet eine signierte Benachrichtigung an Ihren Shop. Das Plugin prüft die Signatur mit dem CRC-Schlüssel, der Merchant ID und der POS ID; dass die Session für diese Bestellung und im selben Modus registriert wurde; und dass Betrag und Währung mit dem Zahlungsversuch und dem aktuellen Bestellbetrag übereinstimmen. Erst dann verifiziert es die Transaktion bei Przelewy24 (Przelewy24 schreibt nur verifizierte Zahlungen gut) und markiert die Bestellung als bezahlt. Webhooks ohne gültige Signatur werden abgelehnt.

Nach der Zahlung kehrt der Kunde zur Seite „Bestellung eingegangen“ zurück. Ist die Benachrichtigung noch nicht eingegangen, fragt das Plugin bei Przelewy24 den Transaktionsstatus per authentifizierter Server-zu-Server-Anfrage ab (höchstens einmal alle 10 Sekunden pro Bestellung) und wendet dieselben Prüfungen an. Die Rückkehrseite allein markiert eine Bestellung nie als bezahlt. Solange die Zahlung nicht bestätigt ist, zeigt die Seite We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: mit einer Schaltfläche Pay again, die die Seite Pay for order öffnet. Steht die Bestellung auf Wartend, zeigt die Seite Your payment is being verified. We will send you an e-mail as soon as it is confirmed. Eine später auf einer älteren Przelewy24-Seite derselben Bestellung getätigte Zahlung wird weiterhin akzeptiert.

Kann die Zahlung nicht gestartet werden, sieht der Kunde eine kurze Meldung: Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (der Grund wird ins Protokoll geschrieben), Payment gateway is not configured properly. Please contact the administrator. (Schlüssel des aktuellen Modus fehlen), eine Meldung, dass Przelewy24 keine Zahlungen in der Bestellwährung annehmen kann, oder The order total must be greater than zero. Eine Bestellung, die bereits bezahlt ist oder auf Wartend steht, wird nicht erneut an Przelewy24 gesendet (This order does not need a payment any more.).

Die Zahlungsmethode funktioniert an der klassischen Kasse, im Kassen-Block und auf der Seite Pay for order. Sie ist mit der Hochleistungs-Bestellspeicherung von WooCommerce (HPOS) kompatibel.

Das Plugin unterstützt keine gespeicherten Karten oder Ein-Klick-Zahlungen, keine Abonnements oder wiederkehrenden Zahlungen, keine Auswahl der P24-Zahlungsmethode (zum Beispiel ein BLIK-Codefeld) auf Ihrer Kassenseite, keine Ratenzahlungs-Widgets und übermittelt keine Warenkorbinhalte an Przelewy24.

Bestellungen und Erstattungen

Bestellstatus

Pending payment: Der Kunde wurde zu Przelewy24 weitergeleitet und hat noch nicht bezahlt, oder die Zahlung ist noch nicht bestätigt.

Processing or Completed: Die Zahlung wurde verifiziert. WooCommerce setzt „In Bearbeitung“ oder bei Bestellungen, die nur virtuelle, herunterladbare Produkte enthalten, „Abgeschlossen“. Die Bestellnotiz zeigt die P24-Bestellnummer, den Betrag und den Modus. Die Transaktions-ID der Bestellung ist die P24-Bestellnummer. Jede Zahlung wird genau einmal verbucht.

On hold: Der von Przelewy24 gemeldete Betrag oder die Währung weicht von der Bestellung ab (zum Beispiel wurde die Bestellsumme geändert, nachdem die Zahlung gestartet wurde); die Zahlung wurde nicht bestätigt, und die Notiz weist darauf hin. Oder die Zahlung ist eingegangen und wurde für eine stornierte Bestellung verifiziert; die Bestellung wird nicht stillschweigend wieder geöffnet, die Notiz bittet Sie, sie zu versenden oder die Zahlung zu erstatten. Prüfen Sie die Zahlung im Przelewy24-Panel.

Trifft eine zweite Zahlung für eine bereits bezahlte oder erstattete Bestellung ein (ein älterer Zahlungslink, zwei Browser-Tabs), wird sie nicht bestätigt, sodass Przelewy24 sie nicht gutschreibt. Eine Notiz an der Bestellung bittet Sie, sie im Przelewy24-Panel zu prüfen und bei Bedarf dem Käufer zurückzuerstatten.

Erstattungen

Öffnen Sie die Bestellung, klicken Sie auf Refund, geben Sie den Betrag ein und klicken Sie auf Refund via Przelewy24. Vollständige und teilweise Erstattungen werden unterstützt. Die Erstattung wird in dem Modus übermittelt, in dem die Zahlung getätigt wurde (Sandbox oder Live), daher müssen die Schlüssel dieses Modus eingerichtet sein. Przelewy24 verarbeitet Erstattungen asynchron: Die Bestellnotiz vermerkt zunächst, dass die Erstattung angefordert wurde; das Ergebnis kommt später an der Benachrichtigungs-URL an und wird als Notiz hinzugefügt: Przelewy24: refund of … completed. oder eine Notiz, dass die Erstattung abgelehnt wurde und das Geld nicht zurückgebucht wurde. Wird eine Erstattung abgelehnt, prüfen Sie sie im Przelewy24-Panel; die bereits in WooCommerce erfasste Erstattung wird nicht automatisch entfernt.

Lehnt Przelewy24 den Erstattungsantrag ab, zeigt WooCommerce Przelewy24 refund failed: mit dem Grund an, und es wird keine Erstattung erfasst. Direkt im Przelewy24-Panel vorgenommene Erstattungen werden nicht in die Bestellung übernommen.

Lizenzschlüssel

Das Plugin arbeitet mit einem VibeFox-Lizenzschlüssel von vibefox.net. Der Lizenzblock befindet sich oben unter WooCommerce > Settings > Payments > Przelewy24. 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 auf einer Domain. Das Entfernen des Schlüssels von einer Website gibt deren Domain-Platz nicht frei. Geben Sie den Platz in Ihrem vibefox.net-Konto frei.

Ohne aktiven Schlüssel wird Przelewy24 Kunden an der Kasse nicht angezeigt. Wird dennoch eine Zahlung gestartet, sieht der Kunde This payment method is not available. Please choose another one. Angemeldete Shop-Manager 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. Ein Hinweis erscheint auf der Plugins-Seite und auf WooCommerce-Seiten. Bestehende Bestellungen sind nicht betroffen: Bereits begonnene Zahlungen werden weiterhin bestätigt, und Erstattungen funktionieren.

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

Fehlerbehebung

Przelewy24 erscheint nicht an der Kasse: Prüfen Sie, ob die Lizenz aktiv ist, Enable/Disable eingeschaltet ist, Merchant ID, API key und CRC key des aktuellen Modus eingegeben sind (die Sandbox-Schlüssel, solange Test Mode aktiv ist, sonst die Live-Schlüssel; Merchant ID und POS ID nur Ziffern) und die Bestellwährung PLN, EUR, GBP oder CZK ist. Die Warnungen oben in den Einstellungen nennen das Problem. Entwickler können die Währungsliste mit dem Filter wc_p24_supported_currencies ändern (nur Währungen mit zwei Dezimalstellen, die für Ihr Przelewy24-Konto aktiviert sind).

Die Zahlung ging durch, aber die Bestellung bleibt im Status Pending payment: Die Benachrichtigung von Przelewy24 hat Ihren Shop nicht erreicht, und der Kunde ist nicht zur Seite „Bestellung eingegangen“ zurückgekehrt. Prüfen Sie, ob die unter Payment notifications angezeigte URL aus dem Internet erreichbar ist (kein Wartungsmodus, keine Firewall und keine HTTP-Authentifizierung vor /wc-api/wc_p24_payment/) und ob Merchant ID, POS ID und CRC key des Modus der Zahlung korrekt sind. Abgelehnte Benachrichtigungen werden unter WooCommerce > Status > Logs, Quelle wcp_przelewy24_payment, protokolliert, auch wenn Debug Log ausgeschaltet ist.

So beantwortet der Shop Benachrichtigungen: Eine verarbeitete, wiederholte oder unbekannte Benachrichtigung wird mit HTTP 200 beantwortet. Andernfalls sendet Przelewy24 sie später erneut: 400 (fehlende oder fehlerhafte Daten), 401 Invalid signature (falscher CRC-Schlüssel, andere Merchant ID oder POS ID oder eine mit den Schlüsseln des anderen Modus als der Zahlung signierte Benachrichtigung), 405 (kein POST-Request), 500 Verification failed (die Verifizierung bei Przelewy24 ist fehlgeschlagen; einmalig wird eine Notiz zur Bestellung hinzugefügt) und 503 Busy, retry later (die Bestellung wurde im selben Moment von einer anderen Anfrage aktualisiert).

Der Kunde sieht Payment error: Przelewy24 could not start the payment: Przelewy24 hat die Transaktion abgelehnt, meist wegen falscher Schlüssel des aktuellen Modus (Sandbox-Schlüssel funktionieren nur im Sandbox-Modus, Live-Schlüssel nur im Live-Modus). Die Fehlermeldung von Przelewy24 steht im Protokoll.

Die Bestellung ist nach der Zahlung On hold: Lesen Sie die Bestellnotiz. Betrag oder Währung wichen von der Bestellung ab, oder die Zahlung kam für eine stornierte Bestellung an. Prüfen Sie die Zahlung im Przelewy24-Panel und bearbeiten Sie dann die Bestellung oder erstatten Sie die Zahlung.

Eine Erstattung schlägt fehl: This order has no verified Przelewy24 payment. Cannot process refund. bedeutet, dass die Bestellung nicht über eine verifizierte Przelewy24-Zahlung bezahlt wurde. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (bzw. dasselbe für Live) bedeutet, dass die Schlüssel des Modus der Zahlung entfernt wurden; geben Sie sie erneut ein.

Der Lizenzblock zeigt einen Fehler: 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. Der Lizenzschlüssel und der Lizenzstatus dieses Plugins sowie die kurzlebigen Markierungen der Rückkehrseite werden immer entfernt. Die Plugin-Einstellungen und seine Protokolle (Protokolldateien, auch rotierte, und Datenbank-Protokolleinträge der Quelle wcp_przelewy24_payment) werden nur entfernt, wenn Delete data on uninstall aktiviert war. Andernfalls bleiben sie für eine spätere Neuinstallation erhalten. Bestehende Bestellungen behalten ihre Zahlungsnotizen, Transaktions-IDs und Przelewy24-Zahlungsdaten.

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