# 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[​](#features "Direkter Link zu 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[​](#getting-started "Direkter Link zu 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](https://github.com/wcpos/woocommerce-gateway-template), 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[​](#manual-setup "Direkter Link zu 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                       | Eingabe                                                   | Beispiel                              |
| --------------------------------- | --------------------------------------------------------- | ------------------------------------- |
| `{{GATEWAY_NAME}}`                | Anzeigename Ihres Zahlungsgateways                        | Barzahlung                            |
| `{{GATEWAY_SLUG}}`                | URL-sicherer Bezeichner (Kleinbuchstaben, Bindestriche)   | bargeld-zahlung                       |
| `{{GATEWAY_DESCRIPTION}}`         | Kurze Beschreibung des Zahlungsgateways                   | Bargeldzahlungen in WCPOS akzeptieren |
| `{{GATEWAY_DEFAULT_DESCRIPTION}}` | Text, der dem Kassenpersonal beim Checkout angezeigt wird | Am POS mit Bargeld bezahlen           |
| `{{GITHUB_USERNAME}}`             | Ihr GitHub-Benutzername                                   | max-mustermann                        |
| `{{REPO_NAME}}`                   | Ihr Repository-Name                                       | bargeld-zahlungsgateway               |
| `{{AUTHOR_NAME}}`                 | Ihr Name                                                  | Max Mustermann                        |
| `{{GATEWAY_ID}}`                  | Slug mit Unterstrichen statt Bindestrichen                | bargeld\_zahlung                      |
| `{{GATEWAY_CLASS_NAME}}`          | Jedes Wort großgeschrieben, mit Unterstrichen verbunden   | Bargeld\_Zahlung                      |
| `{{GATEWAY_FUNCTION_PREFIX}}`     | Entspricht der Gateway-ID                                 | bargeld\_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[​](#how-it-works "Direkter Link zu 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[​](#customising-your-gateway "Direkter Link zu Gateway anpassen")

### Zahlungsfelder hinzufügen[​](#adding-payment-fields "Direkter Link zu 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[​](#changing-payment-behaviour "Direkter Link zu 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[​](#making-changes-and-updating "Direkter Link zu Ä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[​](#automated-releases-with-github "Direkter Link zu 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[​](#troubleshooting "Direkter Link zu 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[​](#requirements "Direkter Link zu Anforderungen")

WCPOS

<!-- -->

: Pro-Version für den POS-Checkout erforderlich

WordPress

<!-- -->

: WordPress mit installiertem WooCommerce

PHP

<!-- -->

: Grundlegende PHP-Kenntnisse zum Anpassen des Gateways

## Ressourcen[​](#resources "Direkter Link zu Ressourcen")

* **GitHub**: [woocommerce-gateway-template](https://github.com/wcpos/woocommerce-gateway-template)
* **WooCommerce Zahlungsgateway-API**: [WC\_Payment\_Gateway-Dokumentation](https://woocommerce.github.io/code-reference/classes/WC-Payment-Gateway.html)

### Beispiel-Gateways[​](#example-gateways "Direkter Link zu Beispiel-Gateways")

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

* **[Rechnung per E-Mail](/de/payment/gateways/email-invoice.md)** — Sendet eine Rechnung per E-Mail, damit der Kunde später bezahlen kann
* **[Web-Checkout](/de/payment/gateways/web-checkout.md)** — Leitet zur Zahlung an den Webshop weiter