Salta al contenuto principale
Versione: 1.x

Template Gateway

Il Template Gateway di WooCommerce fornisce un punto di partenza per creare i propri gateway di pagamento personalizzati per WooCommerce POS. Questo template include tutto il codice di base e la struttura necessaria per costruire un gateway di pagamento completamente funzionante.

Caratteristiche​

  • Template Completo: Struttura gateway pronta all'uso con tutti i metodi richiesti
  • Integrazione POS: Pre-configurato per la compatibilità con WooCommerce POS
  • Impostazione Automatica: Personalizzazione del template basata su script
  • Migliori Pratiche: Segue gli standard di codifica di WordPress e WooCommerce
  • Estensibile: Facile da modificare ed estendere per fornitori di pagamento specifici

Iniziare​

Opzione 1: Generazione Automatica del Template​

Il template include uno script che personalizza automaticamente il template per il tuo gateway specifico:

  1. Clona il Repository:

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

  2. Esegui lo Script di Configurazione:

    ./create-gateway.sh

  3. Segui le Istruzioni:

    • Inserisci il nome del tuo gateway (es. "Il Mio Gateway di Pagamento")
    • Inserisci uno slug per il gateway (es. "il-mio-pagamento")
    • Fornisci una descrizione
    • Lo script genererà un plugin personalizzato

Opzione 2: Utilizzo Manuale del Template​

Se preferisci la personalizzazione manuale:

  1. Scarica il Template:

  2. Personalizza il Template:

    • Sostituisci {{GATEWAY_NAME}} con il nome visualizzato del tuo gateway
    • Sostituisci {{GATEWAY_SLUG}} con l'identificatore unico del tuo gateway
    • Sostituisci {{GATEWAY_DESCRIPTION}} con la descrizione del tuo gateway

  3. Rinomina i File:

    • Rinomina wcpos-{{GATEWAY_SLUG}}.php per corrispondere al tuo slug del gateway
    • Aggiorna le intestazioni dei file e le informazioni sul plugin

Struttura del Template​

File Principale del Plugin​

Il file principale del plugin (wcpos-{{GATEWAY_SLUG}}.php) contiene:

  • Intestazione del Plugin: Informazioni sul plugin di WordPress
  • Classe Gateway: Classe principale del gateway di pagamento
  • Inizializzazione: Configurazione del plugin e hook
  • Integrazione: Compatibilità con WooCommerce POS

Componenti Chiave​

Struttura della Classe Gateway:

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() { }
}

Guida alla Personalizzazione​

Configurazione di Base​

  1. Informazioni sul Gateway:

    $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. Caratteristiche Supportate:

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

Elaborazione dei Pagamenti​

La logica principale del pagamento va nel metodo 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'
        );
    }
}

Impostazioni per l'Amministratore​

Configura le impostazioni per l'amministratore 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
    );
}

Integrazione POS​

Per funzionalità specifiche del POS, implementa:

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();
    }
}

Migliori Pratiche di Sviluppo​

Standard di Codifica​

  • Standard di Codifica di WordPress: Segui gli standard di codifica PHP di WordPress
  • Linee Guida di WooCommerce: Attieniti alle pratiche di sviluppo di WooCommerce
  • Sicurezza: Sanitizza gli input, valida i dati, utilizza nonce
  • Internazionalizzazione: Rendi le stringhe traducibili utilizzando __() e _e()

Gestione degli Errori​

// 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' );
}

Logging​

// 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 ) );
}

Testare il Tuo Gateway​

Ambiente di Sviluppo​

  1. Modalità di Test: Implementare sempre una modalità di test/sandbox
  2. Logging di Debug: Includere un logging completo per la risoluzione dei problemi
  3. Scenari di Errore: Testare varie condizioni di errore
  4. Test per il POS: Testare specificamente nell'ambiente POS

Casi di Test​

  • Pagamenti Riusciti: Verificare che gli ordini completino correttamente
  • Pagamenti Falliti: Garantire una gestione degli errori corretta
  • Rimborsi: Testare la funzionalità di rimborso se supportata
  • Casi Limite: Testare con vari importi e configurazioni degli ordini

Distribuzione​

Imballaggio del Plugin​

  1. Rimuovere i File di Sviluppo: Pulisci i file di test e gli strumenti di sviluppo
  2. Controllo della Versione: Aggiorna i numeri di versione nell'intestazione del plugin
  3. Documentazione: Includi README con istruzioni per l'installazione
  4. Pacchetto Zip: Crea un file zip installabile

Distribuzione​

  • Rilasci di GitHub: Utilizza i rilasci di GitHub per la gestione delle versioni
  • Directory dei Plugin di WordPress: Considera di sottoporre a WordPress.org
  • Distribuzione Privata: Ospita sui propri server se necessario

Funzionalità Avanzate​

Webhooks​

Per aggiornamenti sui pagamenti in tempo reale:

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 );
    }
}

Supporto per Abbonamenti​

Per pagamenti ricorrenti:

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

Multi-valuta​

Per pagamenti internazionali:

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

Risorse​

Documentazione​

Repository del Template​

  • GitHub: woocommerce-gateway-template
  • Problemi: Riporta problemi con il template o richiedi funzionalità
  • Contributi: Invia miglioramenti tramite pull request

Ottenere Aiuto​

Per supporto nello sviluppo:

  • Visita il repository di GitHub per problemi specifici sul template
  • Controlla la documentazione per sviluppatori di WooCommerce per domande sull'API
  • Unisciti alla comunità di sviluppatori di WooCommerce per assistenza generale

Gateway Esempio​

Studia questi gateway personalizzati esistenti per esempi di implementazione: