Zum Hauptinhalt springen
Version: 1.x

Gateway-Vorlage

Die WooCommerce Gateway-Vorlage bietet einen Ausgangspunkt für die Erstellung eigener benutzerdefinierter Zahlungsgateways für WooCommerce POS. Diese Vorlage enthält den gesamten erforderlichen Boilerplate-Code und die Struktur, um ein voll funktionsfähiges Zahlungsgateway zu erstellen.

Funktionen​

  • Vollständige Vorlage: Fertige Gateway-Struktur mit allen erforderlichen Methoden
  • POS-Integration: Vorab konfiguriert für die Kompatibilität mit WooCommerce POS
  • Automatisierte Einrichtung: Skriptbasierte Vorlagenanpassung
  • Best Practices: Folgt den Coding-Standards von WordPress und WooCommerce
  • Erweiterbar: Einfach zu modifizieren und an spezifische Zahlungsanbieter anzupassen

Erste Schritte​

Option 1: Automatisierte Vorlagenerstellung​

Die Vorlage enthält ein Skript, das die Vorlage automatisch für Ihr spezifisches Gateway anpasst:

  1. Klonen Sie das Repository:

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

  2. Führen Sie das Einrichtungs-Skript aus:

    ./create-gateway.sh

  3. Folgen Sie den Aufforderungen:

    • Geben Sie den Namen Ihres Gateways ein (z. B. "Mein Zahlungsgateway")
    • Geben Sie einen Gateway-Slug ein (z. B. "mein-zahlungsgateway")
    • Geben Sie eine Beschreibung an
    • Das Skript generiert ein angepasstes Plugin

Option 2: Manuelle Vorlagenverwendung​

Wenn Sie eine manuelle Anpassung bevorzugen:

  1. Laden Sie die Vorlage herunter:

  2. Passen Sie die Vorlage an:

    • Ersetzen Sie {{GATEWAY_NAME}} mit dem Anzeigenamen Ihres Gateways
    • Ersetzen Sie {{GATEWAY_SLUG}} mit der eindeutigen Kennung Ihres Gateways
    • Ersetzen Sie {{GATEWAY_DESCRIPTION}} mit der Beschreibung Ihres Gateways

  3. Benennen Sie Dateien um:

    • Benennen Sie wcpos-{{GATEWAY_SLUG}}.php um, um mit Ihrem Gateway-Slug übereinzustimmen
    • Aktualisieren Sie die Dateiköpfe und Plugin-Informationen

Vorlagenstruktur​

Haupt-Plugin-Datei​

Die Haupt-Plugin-Datei (wcpos-{{GATEWAY_SLUG}}.php) enthält:

  • Plugin-Kopf: Informationen zum WordPress-Plugin
  • Gateway-Klasse: Hauptklasse für das Zahlungsgateway
  • Initialisierung: Plugin-Einrichtung und Hooks
  • Integration: Kompatibilität mit WooCommerce POS

Schlüsselkomponenten​

Gateway-Klassenstruktur:

class WCPOS_Gateway_{{GATEWAY_CLASS}} extends WC_Payment_Gateway {
    // Gateway configuration
    public function __construct() { }
    
    // Admin settings form
    public function init_form_fields() { }
    
    // Process payment (main logic goes here)
    public function process_payment( $order_id ) { }
    
    // POS-specific methods
    public function payment_fields() { }
}

Anpassungsleitfaden​

Grundkonfiguration​

  1. Gateway-Informationen:

    $this->id = 'your_gateway_id';
    $this->title = 'Your Gateway Name';
    $this->description = 'Gateway description for customers';
    $this->method_title = 'Admin title';
    $this->method_description = 'Admin description';

  2. Unterstützte Funktionen:

    $this->supports = array(
        'products',
        'refunds',
        'subscriptions', // if applicable
    );

Zahlungsabwicklung​

Die Kernlogik für Zahlungen erfolgt in der Methode process_payment():

public function process_payment( $order_id ) {
    $order = wc_get_order( $order_id );
    
    // Your payment processing logic here
    // Example: API calls, validation, etc.
    
    if ( $payment_successful ) {
        $order->payment_complete();
        return array(
            'result' => 'success',
            'redirect' => $this->get_return_url( $order )
        );
    } else {
        wc_add_notice( 'Payment failed', 'error' );
        return array(
            'result' => 'failure'
        );
    }
}

Admin-Einstellungen​

Konfigurieren Sie die Admin-Einstellungen in init_form_fields():

public function init_form_fields() {
    $this->form_fields = array(
        'enabled' => array(
            'title' => 'Enable/Disable',
            'type' => 'checkbox',
            'label' => 'Enable Your Gateway',
            'default' => 'yes'
        ),
        'api_key' => array(
            'title' => 'API Key',
            'type' => 'text',
            'description' => 'Enter your API key',
            'default' => '',
            'desc_tip' => true,
        ),
        // Add more settings as needed
    );
}

POS-Integration​

Für POS-spezifische Funktionen implementieren Sie:

public function payment_fields() {
    // Custom payment form for POS
    if ( is_admin() && isset( $_GET['page'] ) && $_GET['page'] === 'wc-pos' ) {
        // POS-specific payment fields
        echo '<div class="pos-payment-fields">';
        // Your custom POS interface
        echo '</div>';
    } else {
        // Standard web checkout fields
        parent::payment_fields();
    }
}

Entwicklungsbeste Praktiken​

Codestandards​

  • WordPress-Coding-Standards: Folgen Sie den PHP-Coding-Standards von WordPress
  • WooCommerce-Richtlinien: Halten Sie sich an die Entwicklungspraktiken von WooCommerce
  • Sicherheit: Eingaben bereinigen, Daten validieren, Nonces verwenden
  • Internationalisierung: Machen Sie Zeichenfolgen mit __() und _e() übersetzbar

Fehlerbehandlung​

// Proper error handling
try {
    $result = $this->process_api_call( $data );
    if ( is_wp_error( $result ) ) {
        throw new Exception( $result->get_error_message() );
    }
} catch ( Exception $e ) {
    $order->add_order_note( 'Payment failed: ' . $e->getMessage() );
    wc_add_notice( 'Payment processing error', 'error' );
    return array( 'result' => 'failure' );
}

Protokollierung​

// Add logging for debugging
if ( $this->debug ) {
    $this->log( 'Payment processing started for order ' . $order_id );
}

private function log( $message ) {
    if ( empty( $this->logger ) ) {
        $this->logger = wc_get_logger();
    }
    $this->logger->info( $message, array( 'source' => $this->id ) );
}

Testen Ihres Gateways​

Entwicklungsumgebung​

  1. Testmodus: Implementieren Sie immer einen Test-/Sandboxmodus
  2. Debug-Protokollierung: Umfassende Protokollierung für die Fehlersuche einbeziehen
  3. Fehler-Szenarien: Testen Sie verschiedene Fehlerbedingungen
  4. POS-Tests: Besondere Tests in der POS-Umgebung durchführen

Testfälle​

  • Erfolgreiche Zahlungen: Überprüfen Sie, ob Bestellungen korrekt abgeschlossen werden
  • Fehlgeschlagene Zahlungen: Stellen Sie sicher, dass die Fehlerbehandlung ordnungsgemäß funktioniert
  • Rückerstattungen: Testen Sie die Rückerstattungsfunktionalität, falls unterstützt
  • Randfälle: Testen Sie mit verschiedenen Bestellmengen und -konfigurationen

Bereitstellung​

Plugin-Paketierung​

  1. Entwicklungsdateien entfernen: Testdateien und Entwicklungstools aufräumen
  2. Versionskontrolle: Versionsnummern im Plugin-Kopf aktualisieren
  3. Dokumentation: README mit Installationsanweisungen einfügen
  4. Zip-Paket: Erstellen Sie eine installierbare Zip-Datei

Verteilung​

  • GitHub-Releases: Verwenden Sie GitHub-Releases für das Versionsmanagement
  • WordPress-Plugin-Verzeichnis: Erwägen Sie die Einreichung bei WordPress.org
  • Private Verteilung: Bei Bedarf auf eigenen Servern hosten

Erweiterte Funktionen​

Webhooks​

Für Echtzeit-Zahlungsaktualisierungen:

public function handle_webhook() {
    $payload = file_get_contents( 'php://input' );
    $data = json_decode( $payload, true );
    
    // Verify webhook signature
    if ( $this->verify_webhook_signature( $payload ) ) {
        $this->process_webhook_data( $data );
    }
}

Abonnements Unterstützung​

Für wiederkehrende Zahlungen:

// Add subscription support
$this->supports[] = 'subscriptions';
$this->supports[] = 'subscription_cancellation';
$this->supports[] = 'subscription_suspension';

Mehrwährungsfähigkeit​

Für internationale Zahlungen:

public function get_supported_currencies() {
    return array( 'USD', 'EUR', 'GBP', 'CAD' );
}

Ressourcen​

Dokumentation​

Vorlagen-Repository​

  • GitHub: woocommerce-gateway-template
  • Issues: Melden Sie Probleme mit der Vorlage oder fordern Sie Funktionen an
  • Beiträge: Verbesserungen über Pull-Requests einreichen

Hilfe erhalten​

Für Unterstützung bei der Entwicklung:

  • Besuchen Sie das GitHub-Repository für vorlagenbezogene Probleme
  • Überprüfen Sie die WooCommerce-Entwicklerdokumentation bei API-Fragen
  • Treten Sie der WooCommerce-Entwicklergemeinschaft für allgemeine Hinweise bei

Beispiel-Gateways​

Studieren Sie diese bestehenden benutzerdefinierten Gateways für Implementierungsbeispiele: