Gateway-Vorlage

Die Gateway-Vorlage gibt Ihnen einen Ausgangspunkt für den Aufbau Ihres eigenen POS-zugelassenen Zahlungsgateways. Sie erzeugt ein funktionsfähiges WordPress-Plugin mit einer einzigen PHP-Datei, die Sie installieren und an Ihre Bedürfnisse anpassen können.

Funktionen

Minimaler Code

Eine einzige PHP-Datei mit nur den notwendigsten Inhalten — leicht zu lesen und zu modifizieren

Nur POS

Standardmäßig beim Web-Checkout deaktiviert, über die WCPOS-Einstellungen aktiviert

Automatisierte Einrichtung

Ein Shell-Skript erledigt all die Platzhalterersetzung für Sie

GitHub-Releases

Schieben Sie eine Versionsaktualisierung, und GitHub Actions erstellt eine herunterladbare ZIP-Datei

Erste Schritte

1

Klonen Sie das Template-Repository

git clone https://github.com/wcpos/woocommerce-gateway-template.git
cd woocommerce-gateway-template

Oder klicken Sie auf die Schaltfläche Dieses Template verwenden im GitHub-Repository, um Ihre eigene Kopie zu erstellen.

2

Führen Sie das Einrichtungs-Skript aus

./create-gateway.sh

Das Skript fragt nach einigen Details — Ihrem Gateway-Namen, einer kurzen Beschreibung und Ihrem GitHub-Benutzernamen — und erstellt dann ein einsatzbereites Plugin in einem von Ihnen gewählten Verzeichnis.

3

Installieren Sie das Plugin

Sie haben zwei Optionen:

Option A — Ordner direkt kopieren (wenn Sie Serverzugriff haben): Kopieren Sie den generierten Gateway-Ordner in das Verzeichnis wp-content/plugins/ Ihrer Seite.

Option B — Zippen und hochladen (am einfachsten für die meisten Menschen):

1. Komprimieren Sie den generierten Ordner in eine .zip-Datei
2. Gehen Sie in WordPress zu Plugins > Neu hinzufügen > Plugin hochladen
3. Wählen Sie die Zip-Datei aus und klicken Sie auf Jetzt installieren

4

Aktivieren in WCPOS

1. Gehen Sie zu WP Admin > WCPOS > Einstellungen > Checkout
2. Finden Sie Ihr neues Gateway in der Liste und aktivieren Sie es

Hinweis

Das Gateway ist standardmäßig beim regulären Web-Checkout deaktiviert. WCPOS steuert, welche Gateways im POS über die eigenen Einstellungen angezeigt werden.

Manuelle Einrichtung

Wenn Sie das Skript nicht verwenden möchten, können Sie die Platzhalter selbst ersetzen. Öffnen Sie jede Datei in einem Texteditor und suchen und ersetzen Sie Folgendes:

Platzhalter	Was einzugeben ist	Beispiel
{{GATEWAY_NAME}}	Der Anzeigename Ihres Gateways	Barzahlung
{{GATEWAY_SLUG}}	Ein URL-sicherer Bezeichner (kleinbuchstaben, Bindestriche)	barzahlung
{{GATEWAY_DESCRIPTION}}	Kurze Beschreibung des Gateways	Akzeptiert Barzahlungen in WCPOS
{{GATEWAY_DEFAULT_DESCRIPTION}}	Text, der dem Kassierer beim Checkout angezeigt wird	Bezahlen Sie mit Bargeld am Verkaufsort
{{GITHUB_USERNAME}}	Ihr GitHub-Benutzername	kilbot
{{REPO_NAME}}	Ihr Repository-Name	barzahlungs-gateway
{{AUTHOR_NAME}}	Ihr Name	kilbot
{{GATEWAY_ID}}	Slug mit Unterstrichen statt Bindestrichen	bar_zahlung
{{GATEWAY_CLASS_NAME}}	Jedes Wort großgeschrieben, durch Unterstriche verbunden	Bar_Zahlung
{{GATEWAY_FUNCTION_PREFIX}}	Dasselbe wie Gateway-ID	bar_zahlung

Benennen Sie dann wcpos-{{GATEWAY_SLUG}}.php um, um mit Ihrem Slug übereinzustimmen (z. B. wcpos-barzahlung.php).

Tipp

Das Einrichtungs-Skript leitet GATEWAY_ID, GATEWAY_CLASS_NAME und GATEWAY_FUNCTION_PREFIX automatisch aus dem Namen und Slug ab, sodass Sie nur darüber nachdenken müssen, wenn Sie die manuelle Einrichtung durchführen.

Funktionsweise

Das generierte Plugin registriert eine WooCommerce-Zahlungsgateway-Klasse. Hier sind die wichtigsten Punkte, die Sie wissen sollten:

• $this->enabled = 'no' — Das Gateway wird beim Web-Checkout ausgeblendet. WCPOS aktiviert es im POS basierend auf Ihren POS-Einstellungen.
• process_payment() — Ruft $order->payment_complete() auf, das die Bestellung als bezahlt markiert und die Bestandsreduzierung automatisch übernimmt.
• init_form_fields() — Definiert die Titel- und Beschreibungsfelder, die in WooCommerce-Einstellungen erscheinen.

Anpassen Ihres Gateways

Hinzufügen von Zahlungsfeldern

Wenn Ihr Gateway Eingaben vom Kassierer benötigt (zum Beispiel eine Referenznummer), überschreiben Sie die Methode payment_fields():

public function payment_fields() {
    if ( $this->description ) {
        echo wpautop( wptexturize( $this->description ) );
    }

    woocommerce_form_field( 'my_gateway_reference', array(
        'type'        => 'text',
        'label'       => __( 'Reference Number', 'your-text-domain' ),
        'required'    => true,
    ) );
}

Sie können dann den eingegebenen Wert in process_payment() über $_POST['my_gateway_reference'] lesen. Denken Sie daran, jede Eingabe mit sanitize_text_field() zu bereinigen.

Ändern des Zahlungsverhaltens

Die Standardvorlage markiert Bestellungen sofort als bezahlt. Wenn Ihr Workflow eine spätere Zahlung erfordert (wie bei einer Rechnung), ersetzen Sie payment_complete() durch ein Statusupdate:

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );

    // Set to pending — the customer will pay later.
    $order->update_status( 'pending', __( 'Awaiting payment', 'your-text-domain' ) );

    // Stock must be reduced manually when not using payment_complete().
    wc_reduce_stock_levels( $order_id );

    return array(
        'result'   => 'success',
        'redirect' => $this->get_return_url( $order ),
    );
}

Änderungen vornehmen und aktualisieren

Nachdem Sie Ihr Gateway installiert haben, können Sie die Plugin-Datei weiterhin bearbeiten, um die Zahlungslogik anzupassen. Um eine aktualisierte Version zu installieren:

1. Bearbeiten Sie wcpos-your-slug.php im generierten Ordner
2. Aktualisieren Sie die Version:-Nummer im Plugin-Header (z. B. von 0.1.0 auf 0.2.0)
3. Zippen Sie den Ordner und laden Sie ihn erneut über Plugins > Neu hinzufügen > Plugin hochladen hoch oder ersetzen Sie den Ordner direkt in wp-content/plugins/

Tipp

WordPress wird fragen, ob Sie das bestehende Plugin ersetzen möchten, wenn Sie eine ZIP mit demselben Plugin-Namen hochladen — klicken Sie auf Aktuelles durch hochgeladenes ersetzen, um zu aktualisieren.

Automatisierte Releases mit GitHub

Wenn Sie Ihr Gateway in ein GitHub-Repository pushen, enthält die Vorlage einen GitHub Actions-Workflow, der Releases automatisch erstellt:

1. Aktualisieren Sie die Version:-Nummer im Plugin-Header
2. Bestätigen und pushen Sie in den main-Branch
3. GitHub Actions erkennt die Versionsänderung und erstellt ein neues Release mit einer herunterladbaren ZIP

Andere Benutzer können dann die ZIP von der Releases-Seite Ihres Repositorys herunterladen und wie ein beliebiges WordPress-Plugin installieren.

Fehlersuche

Gateway erscheint nicht im POS

• Überprüfen Sie, ob das Plugin in WP Admin > Plugins aktiviert ist
• Gehen Sie zu WP Admin > WCPOS > Einstellungen > Checkout und stellen Sie sicher, dass das Gateway aktiviert ist
• Überprüfen Sie, ob WooCommerce installiert und aktiv ist

Gateway erscheint beim Web-Checkout

• Stellen Sie sicher, dass $this->enabled = 'no'; im Gateway-Konstruktor gesetzt ist
• WCPOS überschreibt diese Einstellung für POS-Anfragen, sodass das Gateway nur im POS erscheinen sollte

Bestellungen bleiben in 'Wird bearbeitet' statt 'Abgeschlossen'

• WooCommerce setzt den Bestellstatus basierend auf Produkttypen. Bestellungen, die physische Produkte enthalten, bleiben "Wird bearbeitet" — das ist normales WooCommerce-Verhalten. Nur Bestellungen mit ausschließlich virtuellen oder herunterladbaren Produkten werden automatisch als "Abgeschlossen" gekennzeichnet.

Ressourcen

• GitHub: woocommerce-gateway-template
• WooCommerce-Zahlungsgateway-API: WC_Payment_Gateway-Dokumentation

Beispielgateways

Diese bestehenden Gateways wurden mit demselben Ansatz gebaut und sind gute Referenzen:

• E-Mail-Rechnung — Sendet eine Rechnungs-E-Mail, damit der Kunde später bezahlen kann
• Web-Checkout — Leitet zum Webshop für die Zahlung weiter