PostPay — Österreichische Post PostPay¶

Extension for Magento 2¶

Bedienungsanleitung¶

CopeX GmbH
Web: https://copex.io
Email: office@copex.io

Inhaltsverzeichnis¶

Abschnitt	Seite
1 Voraussetzungen	2
2 Konfiguration	2
2.1 PostPay-Einstellungen	2
3 Funktionen	3
3.1 PostPay als Zahlungsmethode im Checkout	3
3.2 Zahlungsanweisungen für Kunden	4
3.3 PostPay Refund	4
4 Einschränkungen	5
5 Fehlerbehandlung	5

1 Voraussetzungen¶

Magento 2.3 oder höher (kompatibel mit 2.4)
PHP 8.1 oder höher
Aktiver PostPay-Vertrag mit der Österreichischen Post
API-Zugangsdaten für die PostPay-Refund-API (API Key + API Secret)
Optional: CopeX PLC-Modul — übernimmt PostPay-Refunds automatisch wenn installiert (siehe Abschnitt 3.3 für die zwei Modi)

2 Konfiguration¶

Die Konfiguration des Moduls finden Sie im Magento 2 Backend unter Shops > Konfiguration > Verkauf > Zahlungsmethoden > Post.at PostPay.

2.1 PostPay-Einstellungen¶

Navigieren Sie zu Shops > Konfiguration > Verkauf > Zahlungsmethoden > Post.at PostPay.

Aktiviert — Schaltet PostPay als Zahlungsmethode im Checkout ein oder aus (Ja / Nein).
Titel — Name der Zahlungsmethode, der im Checkout und in der Bestellübersicht angezeigt wird. Standard: Post Pay.
Neuer Bestellstatus — Bestellstatus, der nach der Bestellaufgabe mit PostPay gesetzt wird (z.B. Ausstehend).
Sortierung — Reihenfolge der Zahlungsmethode im Checkout. Niedrigere Zahlen werden zuerst angezeigt.
PostPay Refund — Informationsblock zur PostPay Rückerstattungsfunktion. Wenn das CopeX PLC-Modul installiert ist, erfolgt die Konfiguration dort unter Shops > Konfiguration > Verkauf > Liefermethoden > PostPay Refund.

2.2 PostPay Refund API (Standalone)¶

Diese Konfigurationsgruppe wird nur benötigt, wenn das CopeX PLC-Modul nicht installiert ist. Mit installiertem PLC-Modul werden dessen API-Credentials verwendet.

Die Einstellungen liegen unter Shops > Konfiguration > Verkauf > Zahlungsmethoden > Post.at PostPay > PostPay Refund API (Standalone).

API Key — Vom Post.at-PostPay-Vertrag bereitgestellter API-Key. Verschlüsselt gespeichert.
API Secret — Zugehöriges Secret. Verschlüsselt gespeichert.
Test Mode — Ja für die Test-Umgebung, Nein für Production. Standardmäßig auf Ja gesetzt.
Test Endpoint — URL der PostPay Test-API. Standard: https://postag.test.apimanagement.ch20.hana.ondemand.com
Production Endpoint — URL der PostPay Production-API. Standard: https://postag.prod.apimanagement.ch20.hana.ondemand.com

3 Funktionen¶

3.1 PostPay als Zahlungsmethode im Checkout¶

Nach der Aktivierung erscheint PostPay im Checkout als wählbare Zahlungsmethode. PostPay ist eine Offline-Zahlungsmethode — die eigentliche Zahlungsabwicklung erfolgt direkt zwischen dem Kunden und der Österreichischen Post, nicht über ein Online-Gateway.

Verfügbarkeit des PostPay-Payments:

PostPay ist ausschließlich unter folgenden Bedingungen verfügbar:

Bedingung	Wert
Land	Nur Österreich (AT)
Währung	Nur Euro (EUR)
Maximaler Bestellwert	3.000 EUR
Virtuelle Produkte	Nicht verfügbar (nur physische Produkte)

Diese Einschränkungen sind fest kodiert und können nicht über die Konfiguration geändert werden.

Ablauf:

Kunde wählt PostPay im Checkout als Zahlungsmethode.
Bestellung wird mit dem konfigurierten Anfangsstatus angelegt.
Händler erstellt Versandlabel (empfohlen: CopeX PLC-Modul).
Paket wird mit PostPay-Sendung verschickt.
Österreichische Post zieht den Betrag beim Kunden nach Lieferung ein.
Händler erhält die Zahlung von der Österreichischen Post.

3.2 Zahlungsanweisungen für Kunden¶

Das Modul zeigt dem Kunden abhängig vom Bestellstatus passende Zahlungsanweisungen:

Bestellstatus	Angezeigte Information
Standardzustand	Informationstext zu PostPay und Hinweis, dass die Zahlung nach Lieferung erfolgt
Storniert	Hinweis, dass die Bestellung storniert wurde
Rechnung erstellt	Hinweis auf die Zahlung nach Sendungserhalt
Gutschrift erstellt	Hinweis auf die laufende Rückerstattung

3.3 PostPay Refund¶

Das Modul unterstützt PostPay-Refunds in zwei Modi. Der aktive Modus wird automatisch zur Laufzeit anhand der installierten Module gewählt.

Modus A — Standalone (ohne CopeX PLC-Modul)¶

Beim Erstellen einer Gutschrift erscheint im Backend ein zusätzliches Eingabefeld „Post-Label / Tracking-Nummer". Dieses Feld ist Pflicht — der Refund kann ohne diese Eingabe nicht abgesendet werden.

Voraussetzungen: - PostPay API Key und API Secret in den PostPay-Einstellungen hinterlegt (siehe Abschnitt 2.2)

Ablauf: 1. Händler legt im Magento-Backend eine Gutschrift für eine PostPay-Bestellung an. 2. Händler gibt die Tracking-Nummer der ursprünglichen Sendung in das neue Eingabefeld ein (max. 22 Zeichen). 3. Beim Klick auf „Refund Offline" wird eine OAuth2-Anfrage an die PostPay-Token-API gesendet, danach eine REST-Refund-Anfrage mit Bearer-Token. (Hinweis: Der Button heißt „Refund Offline", weil PostPay eine Offline-Zahlungsmethode ohne Online-Gateway-Transaction ist — der API-Refund wird aber trotzdem ausgeführt.) 4. Bei Erfolg wird ein Bestellkommentar mit Refund-Betrag und Tracking-Nummer hinzugefügt. 5. Bei Fehler wird die Gutschrift per Magento-Transaction-Rollback verworfen und eine Fehlermeldung angezeigt (inkl. Log-ID der Post.at-Antwort).

Limit: PostPay akzeptiert keine Refunds über 1.200 EUR pro Anfrage (von Post.at vorgegeben). Höhere Beträge müssen in Teil-Refunds aufgeteilt werden.

Modus B — Mit CopeX PLC-Modul¶

Wenn das CopeX PLC-Modul installiert ist, übernimmt dessen Plugin den Refund automatisch. Das Postlabel-Eingabefeld aus Modus A wird in diesem Fall nicht angezeigt.

Voraussetzungen: - CopeX PLC-Modul installiert und konfiguriert - PostPay API Key und API Secret in den PLC-Einstellungen hinterlegt - PLC-Versandlabel für die Bestellung existiert (Tracking-Nummer wird automatisch ausgelesen)

Ablauf: 1. Händler erstellt eine Gutschrift für eine PostPay-Bestellung. 2. Das PLC-Modul liest die Tracking-Nummer aus dem zugehörigen PLC-Versandlabel. 3. Das PLC-Modul sendet automatisch die Refund-Anfrage an die PostPay-API. 4. Bei Erfolg wird ein Bestellkommentar hinzugefügt. 5. Bei Fehler wird die Gutschrift nicht gespeichert.

Die Konfiguration von PostPay Refund (API Key, API Secret) erfolgt im CopeX PLC-Modul unter Shops > Konfiguration > Verkauf > Liefermethoden > PostPay Refund.

4 Einschränkungen¶

PostPay ist ausschließlich für österreichische Lieferadressen verfügbar.
Nur Euro-Bestellungen werden unterstützt.
Warenkörbe mit rein virtuellen Produkten sind nicht berechtigt.
Der maximale Bestellwert ist auf 3.000 EUR begrenzt.

5 Fehlerbehandlung¶

PostPay erscheint nicht im Checkout — Prüfen Sie, ob das Modul aktiviert ist. Stellen Sie sicher, dass die Lieferadresse in Österreich liegt und die Bestellwährung Euro ist. Virtuelle Produkte im Warenkorb verhindern die Anzeige.
„Bitte geben Sie ein Post-Label (Tracking-Nummer) für den PostPay-Refund an." — Beim Erstellen einer Gutschrift im Standalone-Modus (ohne PLC) muss die Tracking-Nummer im Feld „Post-Label / Tracking-Nummer" eingegeben werden.
„PostPay refund API credentials are not configured" — Hinterlegen Sie API Key und API Secret unter Shops > Konfiguration > Verkauf > Zahlungsmethoden > Post.at PostPay > PostPay Refund API (Standalone) (Modus A) bzw. in den PLC-Einstellungen (Modus B).
„PostPay refund amount exceeds 1200 EUR limit" — PostPay akzeptiert pro Refund maximal 1.200 EUR. Bei höheren Beträgen mehrere Teil-Refunds erstellen.
„PostPay refund failed: ... (LogID: ...)" — Die PostPay-API hat den Refund abgelehnt. Die Log-ID kann an den Post.at-Support (andreas.pinterits@post.at) zur Fehleranalyse weitergegeben werden.
PostPay Refund fehlgeschlagen (PLC-Modus) — Prüfen Sie die PostPay API-Zugangsdaten im CopeX PLC-Modul unter Shops > Konfiguration > Verkauf > Liefermethoden > PostPay Refund. Stellen Sie sicher, dass ein PLC-Versandlabel mit Tracking-Nummer für diese Bestellung existiert.
Admin-Benachrichtigung „CopeX PLC nicht installiert" — Diese Benachrichtigung war ursprünglich erforderlich, da PostPay-Refunds das PLC-Modul benötigten. Seit Version 1.1.0 ist das PLC-Modul für Refunds optional. Die Benachrichtigung weist lediglich darauf hin, dass ohne PLC-Modul jeder Refund eine manuelle Eingabe der Tracking-Nummer erfordert.

Lizenz¶

Proprietär — CopeX GmbH. Eine Lizenz pro produktiver Magento-Instanz. Test- und Entwicklungsumgebungen benötigen keine zusätzliche Lizenz.