Vorgio
DE EN

WooCommerce-Plugin — vorgio-for-woocommerce

Ein WordPress-Plugin, das Vorgio in WooCommerce-Shops als Bezahloption an der Kasse einbindet. Kein Code für den Händler — installieren, Token einfügen, Webhook-Secret einfügen, Auslieferungs-Trigger wählen.

Das Plugin bündelt das vorgio-php-SDK mit über PHP-Scoper gepräfixten Namespaces, sodass es nicht mit einem anderen Plugin kollidieren kann, das eine andere SDK-Version mitbringt.

#Installation

Zwei Wege:

 1# Option 1 — in wp-content/plugins klonen
 2cd wp-content/plugins
 3git clone https://github.com/vorgio/vorgio-for-woocommerce
 4cd vorgio-for-woocommerce && composer build  # erzeugt dist/vorgio-for-woocommerce-<version>.zip
 5
 6# Option 2 — Release-ZIP via WP-Admin hochladen
 7# WP-Admin → Plugins → Installieren → Plugin hochladen → vorgio-for-woocommerce-<version>.zip

Aktivieren Sie Vorgio for WooCommerce auf der Plugins-Seite.

#Konfiguration

Im WordPress-Adminbereich: WooCommerce → Einstellungen → Zahlungen → Kauf auf Rechnung (Vorgio).

Feld Was einzutragen ist
API-Token Ihr Vorgio-Token (act_…). Wird über die API-Tokens-Seite Ihres Vorgio-Teams mit dem Preset „Payment-provider integration" ausgestellt.
Webhook-Secret Das Signing-Secret, das angezeigt wurde, als Sie auf der Webhooks-Seite Ihres Vorgio-Teams einen Endpoint unter https://your-shop.example/wp-json/vorgio/v1/webhook hinzugefügt haben.
Auslieferungs-Trigger Wann die WC-Bestellung automatisch über on-hold hinaus weiterspringen soll. Zwei Optionen: On invoice sent (sofort beim invoice.sent-Webhook — Sie vertrauen darauf, dass der Kunde später zahlt) oder On invoice paid (erst, wenn der Händler die Rechnung in Vorgio als bezahlt markiert).
Status nach Trigger Der WooCommerce-Status, der beim Trigger gesetzt wird — processing (Standard) oder completed.
Standardsprache de oder en — die Sprache, in der Vorgio die Rechnungs-E-Mail und das PDF rendert, wenn keine kundenspezifische Sprache vorliegt.
Absendername (Override) Optional — überschreibt den Standard-Absendernamen des Händlers.
Zahlungsfrist (Tage) Wird als due_offset_days auf der Vorgio-Rechnung gesetzt.
Steuersatz (%) Wird als tax_rate weitergereicht. Vorgio berechnet Rechnungssummen aus diesem einen Satz.

Speichern. Die Option „Kauf auf Rechnung (Vorgio)" erscheint nun auf der WC-Kasse.

#So funktioniert es

Wenn ein Kunde an der Kasse „Kauf auf Rechnung (Vorgio)" auswählt:

  1. WC löst woocommerce_checkout_order_processed aus.
  2. Das Plugin mappt die WC-Bestellung → Vorgio-Checkout-Payload:
    • WC-Kunde → Vorgio-Client (mit external_id = "wc_customer_{customer_id}" für angemeldete Käufer oder "wc_order_{order_id}" bei Gast-Bestellungen)
    • WC-Positionen → Rechnungspositionen (Modus fixed, amount_cents aus dem Positionssubtotal)
    • WC-Versandkosten und -Gebühren → zusätzliche Positionen
    • WC-Rabatte → eine einzelne Negativ-Position „Discount"
    • WC-Bestell-ID → metadata.wc_order_id
  3. Ruft serverseitig POST /v1/checkouts mit dem Idempotency-Key wc-order-{id}-{order_key} auf.
  4. Setzt die WC-Bestellung auf on-hold und speichert die Vorgio-Rechnungs-ID, -Nummer und -URL als Bestellmeta.
  5. Der Kunde sieht die WooCommerce-Seite „Bestellung erhalten" und erhält die Vorgio-Rechnungs-E-Mail separat.

Später, wenn Vorgio Webhooks auslöst:

  • invoice.sent → wenn Ihr Auslieferungs-Trigger „On invoice sent" ist, wechselt die WC-Bestellung in den konfigurierten Status nach Trigger. Andernfalls wird nur eine Bestellnotiz hinzugefügt.
  • invoice.paid → die Bestellung wird als bezahlt markiert (payment_complete()) und, wenn der Trigger „On invoice paid" ist, in den konfigurierten Status überführt.

#Bestellverwaltung

Im WC-Bestellungs-Bearbeitungsbildschirm zeigt das Plugin:

  • Vorgio-Rechnungsnummer im Bestelldetailbereich
  • „In Vorgio ansehen"-Link (Deeplink zur Rechnung in Ihrem Vorgio-Team)
  • Bei Fehlern beim Checkout: den Fehlergrund

#Fehler-UX

  • Wenn der Vorgio-Aufruf zur Checkout-Zeit fehlschlägt (Netzwerkfehler, 4xx, 5xx), sieht der Kunde eine freundliche Meldung, dass die Rechnung nicht erstellt werden konnte. Die WC-Bestellung wird mit einer strukturierten privaten Notiz auf failed gesetzt (Validierungsfeldfehler, Retry-After bei Rate-Limit, RFC-7807-type + detail), damit der Händler dem nachgehen kann.
  • Wenn eine Webhook-Zustellung fehlschlägt (Ihr Endpoint ist offline), wiederholt Vorgio die Zustellung gemäß dem dokumentierten Zeitplan und deaktiviert den Endpoint nach 7 Fehlversuchen automatisch (~ 2 Tage). Re-aktivieren Sie den Endpoint anschließend über die Vorgio-Webhooks-Seite.

#Mehrsprachigkeit

Das Plugin setzt client.language aus dem wp_user_locale-Meta der Bestellung (de* → de, en* → en); fehlt es, greift die Standardsprache-Einstellung.

#HPOS

Das Plugin deklariert HPOS-Kompatibilität (Custom Order Tables). Sowohl klassische Post-Tabellen-Bestellungen als auch HPOS-Shops werden unterstützt.

#Kompatibilität

  • WordPress 6.4+
  • WooCommerce 8.0+
  • PHP 8.2+

#Quellcode

github.com/vorgio/vorgio-for-woocommerce. Das Plugin steht unter GPL-2.0-or-later.