Zum Hauptinhalt springen
Version: 1.x

Gateway-Vorlage

Die Gateway-Vorlage bietet einen Ausgangspunkt für den Aufbau eines eigenen Zahlungsgateways nur für POS. Sie erzeugt ein funktionsfähiges WordPress-Plugin mit einer einzelnen PHP-Datei, die installiert und an die eigenen Anforderungen angepasst werden kann.

Funktionen​

Minimaler Code

Eine einzelne PHP-Datei mit nur dem Nötigsten — leicht zu lesen und anzupassen

Nur POS

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

Automatisierte Einrichtung

Ein Shell-Skript übernimmt die gesamte Platzhalter-Ersetzung für Sie

GitHub-Veröffentlichungen

Ein Push einer Versionsanhebung löst GitHub Actions aus und erstellt eine herunterladbare ZIP-Datei

Erste Schritte​

1

Repository der Gateway-Vorlage klonen

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

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

2

Setup-Skript ausführen

./create-gateway.sh

Das Skript fragt einige Angaben ab — den Namen Ihres Zahlungsgateways, eine kurze Beschreibung und Ihren GitHub-Benutzernamen — und erstellt anschließend ein einsatzbereites Plugin in einem Verzeichnis Ihrer Wahl.

3

Plugin installieren

Sie haben zwei Optionen:

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

Option B — Als ZIP-Datei packen und hochladen (für die meisten am einfachsten):

  1. Komprimieren Sie den generierten Ordner in eine Datei mit der Endung .zip
  2. Gehen Sie in WordPress zu Plugins > Installieren > Plugin hochladen
  3. Wählen Sie die ZIP-Datei aus und klicken Sie auf Jetzt installieren
4

In WCPOS aktivieren

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

Das Zahlungsgateway ist standardmäßig im regulären Web-Checkout deaktiviert. WCPOS steuert über eigene Einstellungen, welche Zahlungsgateways im POS 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:

PlatzhalterEingabeBeispiel
{{GATEWAY_NAME}}Anzeigename Ihres ZahlungsgatewaysBarzahlung
{{GATEWAY_SLUG}}URL-sicherer Bezeichner (Kleinbuchstaben, Bindestriche)bargeld-zahlung
{{GATEWAY_DESCRIPTION}}Kurze Beschreibung des ZahlungsgatewaysBargeldzahlungen in WCPOS akzeptieren
{{GATEWAY_DEFAULT_DESCRIPTION}}Text, der dem Kassenpersonal beim Checkout angezeigt wirdAm POS mit Bargeld bezahlen
{{GITHUB_USERNAME}}Ihr GitHub-Benutzernamemax-mustermann
{{REPO_NAME}}Ihr Repository-Namebargeld-zahlungsgateway
{{AUTHOR_NAME}}Ihr NameMax Mustermann
{{GATEWAY_ID}}Slug mit Unterstrichen statt Bindestrichenbargeld_zahlung
{{GATEWAY_CLASS_NAME}}Jedes Wort großgeschrieben, mit Unterstrichen verbundenBargeld_Zahlung
{{GATEWAY_FUNCTION_PREFIX}}Entspricht der Gateway-IDbargeld_zahlung

Benennen Sie anschließend wcpos-{{GATEWAY_SLUG}}.php passend zu Ihrem Slug um (z. B. wcpos-cash-payment.php).

Tipp

Das Einrichtungsskript leitet GATEWAY_ID, GATEWAY_CLASS_NAME und GATEWAY_FUNCTION_PREFIX automatisch aus Name und Slug ab, sodass Sie sich nur bei einer manuellen Einrichtung damit befassen müssen.

Funktionsweise​

Das generierte Plugin registriert eine WooCommerce-Zahlungsgateway-Klasse. Die wichtigsten Punkte:

  • $this->enabled = 'no' — Das Gateway wird im Web-Checkout ausgeblendet. WCPOS aktiviert es im POS anhand Ihrer POS-Einstellungen.
  • process_payment() — Ruft $order->payment_complete() auf. Dadurch wird die Bestellung als bezahlt markiert und die Bestandsreduzierung automatisch ausgeführt.
  • init_form_fields() — Definiert die Felder Titel und Beschreibung, die in den WooCommerce-Einstellungen angezeigt werden.

Gateway anpassen​

Zahlungsfelder hinzufügen​

Wenn Ihr Gateway eine Eingabe durch das Kassenpersonal 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,
    ) );
}

Anschließend können Sie den übermittelten Wert in process_payment() über $_POST['my_gateway_reference'] auslesen. Denken Sie daran, alle Eingaben mit sanitize_text_field() zu bereinigen.

Zahlungsverhalten ändern​

Die Standardvorlage markiert Bestellungen sofort als bezahlt. Wenn Ihr Arbeitsablauf eine spätere Zahlung erfordert (zum Beispiel bei einer Rechnung), ersetzen Sie payment_complete() durch eine Statusaktualisierung:

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​

Nach der Installation Ihres Gateways kann die Plugin-Datei weiter bearbeitet werden, um die Zahlungslogik anzupassen. So installieren Sie eine aktualisierte Version:

  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. Erstellen Sie eine ZIP-Datei des Ordners und laden Sie sie erneut über Plugins > Installieren > Plugin hochladen hoch, oder ersetzen Sie den Ordner direkt in wp-content/plugins/
Tipp

WordPress fragt beim Hochladen einer ZIP-Datei mit demselben Plugin-Namen, ob das vorhandene Plugin ersetzt werden soll — klicken Sie auf Aktuelle Version durch hochgeladene 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. Committen und pushen Sie in den Branch main
  3. GitHub Actions erkennt die Versionsänderung und erstellt ein neues Release mit einer herunterladbaren ZIP-Datei

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

Fehlerbehebung​

Zahlungsgateway erscheint nicht im POS
  • Prüfen Sie, ob das Plugin in WP Admin > Plugins aktiviert ist
  • Öffnen Sie WP Admin > WCPOS > Einstellungen > Checkout und stellen Sie sicher, dass das Zahlungsgateway aktiviert ist
  • Prüfen Sie, ob WooCommerce installiert und aktiv ist
Zahlungsgateway erscheint im Web-Checkout
  • Stellen Sie sicher, dass $this->enabled = 'no'; im Gateway-Konstruktor festgelegt ist
  • WCPOS überschreibt diese Einstellung für POS-Anfragen, daher sollte das Zahlungsgateway nur im POS erscheinen
Bestellungen bleiben auf 'In Bearbeitung' statt 'Abgeschlossen'
  • WooCommerce legt den Bestellstatus anhand der Produkttypen fest. Bestellungen mit physischen Produkten bleiben auf "In Bearbeitung" — dies ist normales WooCommerce-Verhalten. Nur Bestellungen, die ausschließlich virtuelle oder herunterladbare Produkte enthalten, werden automatisch als "Abgeschlossen" markiert.

Anforderungen​

WCPOS: Pro-Version für den POS-Checkout erforderlich
WordPress: WordPress mit installiertem WooCommerce
PHP: Grundlegende PHP-Kenntnisse zum Anpassen des Gateways

Ressourcen​

Beispiel-Gateways​

Diese bestehenden Gateways wurden mit demselben Ansatz erstellt und eignen sich gut als Referenz: