Modello di Gateway

Il Modello di Gateway ti offre un punto di partenza per costruire il tuo gateway di pagamento solo per POS. Produce un plugin WordPress funzionante con un singolo file PHP che puoi installare e personalizzare in base alle tue esigenze.

Caratteristiche

Codice Minimo

Un singolo file PHP con solo le essenziali — facile da leggere e modificare

Solo POS

Disabilitato di default nel checkout web, abilitato attraverso le impostazioni WCPOS

Impostazione Automatizzata

Uno script shell gestisce la sostituzione dei segnaposto per te

Rilascio su GitHub

Fai un bump di versione e GitHub Actions crea un ZIP scaricabile

Introduzione

1

Clona il Repository del Modello

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

Oppure fai clic sul pulsante Usa questo modello nel repository di GitHub per creare una tua copia.

2

Esegui lo Script di Installazione

./create-gateway.sh

Lo script richiede alcuni dettagli: il nome del tuo gateway, una breve descrizione e il tuo nome utente GitHub, quindi genera un plugin pronto all'uso in una directory di tua scelta.

3

Installa il Plugin

Hai due opzioni:

Opzione A — Copia la cartella direttamente (se hai accesso al server): Copia la cartella del gateway generata nella directory wp-content/plugins/ del tuo sito.

Opzione B — Zip e carica (la più semplice per la maggior parte delle persone):

1. Comprimi la cartella generata in un file .zip
2. In WordPress, vai a Plugin > Aggiungi Nuovo > Carica Plugin
3. Scegli il file zip e fai clic su Installa Ora

4

Abilita in WCPOS

1. Vai a WP Admin > WCPOS > Impostazioni > Checkout
2. Trova il tuo nuovo gateway nell'elenco e abilitalo

nota

Il gateway è disabilitato di default nel checkout web regolare. WCPOS controlla quali gateway appaiono nel POS tramite le proprie impostazioni.

Configurazione Manuale

Se preferisci non utilizzare lo script, puoi sostituire i segnaposto tu stesso. Apri ciascun file in un editor di testo e trova-sostituisci il seguente:

Segnaposto	Cosa inserire	Esempio
{{GATEWAY_NAME}}	Nome visualizzato del tuo gateway	Pagamento in Contante
{{GATEWAY_SLUG}}	Un identificatore URL-friendly (minuscolo, trattini)	pagamento-contante
{{GATEWAY_DESCRIPTION}}	Breve descrizione del gateway	Accetta pagamenti in contante in WCPOS
{{GATEWAY_DEFAULT_DESCRIPTION}}	Testo mostrato al cassiere al checkout	Paga in contante al punto vendita
{{GITHUB_USERNAME}}	Il tuo nome utente GitHub	kilbot
{{REPO_NAME}}	Nome del tuo repository	gateway-pagamento-contante
{{AUTHOR_NAME}}	Il tuo nome	kilbot
{{GATEWAY_ID}}	Slug con underscore invece di trattini	pagamento_contante
{{GATEWAY_CLASS_NAME}}	Ogni parola maiuscola, unita da underscore	Pagamento_Contante
{{GATEWAY_FUNCTION_PREFIX}}	Stesso come Gateway ID	pagamento_contante

Quindi rinomina wcpos-{{GATEWAY_SLUG}}.php per corrispondere al tuo slug (ad es., wcpos-pagamento-contante.php).

consiglio

Lo script di installazione deriva automaticamente GATEWAY_ID, GATEWAY_CLASS_NAME e GATEWAY_FUNCTION_PREFIX dal nome e dallo slug, quindi devi pensare a questi solo quando fai una configurazione manuale.

Come Funziona

Il plugin generato registra una classe di gateway di pagamento WooCommerce. Ecco le cose chiave da sapere:

• $this->enabled = 'no' — Il gateway è nascosto dal checkout web. WCPOS lo abilita nel POS in base alle tue impostazioni POS.
• process_payment() — Chiama $order->payment_complete(), che segna l'ordine come pagato e gestisce la riduzione delle scorte automaticamente.
• init_form_fields() — Definisce i campi Titolo e Descrizione che appaiono nelle impostazioni di WooCommerce.

Personalizzazione del Tuo Gateway

Aggiunta di Campi di Pagamento

Se il tuo gateway ha bisogno di input dal cassiere (ad esempio, un numero di riferimento), sovrascrivi il metodo 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,
    ) );
}

Puoi quindi leggere il valore inviato in process_payment() tramite $_POST['my_gateway_reference']. Ricorda di sanitizzare qualsiasi input con sanitize_text_field().

Modifica del Comportamento di Pagamento

Il modello predefinito segna gli ordini come pagati immediatamente. Se il tuo flusso di lavoro richiede il pagamento successivo (come una fattura), sostituisci payment_complete() con un aggiornamento dello stato:

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

Apportare Modifiche e Aggiornamenti

Dopo aver installato il tuo gateway, puoi continuare a modificare il file del plugin per regolare la logica di pagamento. Per installare una versione aggiornata:

1. Modifica wcpos-your-slug.php nella cartella generata
2. Aggiorna il numero Version: nell'intestazione del plugin (ad es., 0.1.0 a 0.2.0)
3. Zip la cartella e caricala di nuovo tramite Plugin > Aggiungi Nuovo > Carica Plugin, oppure sostituisci direttamente la cartella in wp-content/plugins/

consiglio

WordPress chiederà se vuoi sostituire il plugin esistente quando carichi uno zip con lo stesso nome del plugin — fai clic su Sostituisci quello attuale con caricato per aggiornare.

Rilascio Automatizzato con GitHub

Se carichi il tuo gateway in un repository GitHub, il modello include un workflow di GitHub Actions che crea rilasci automaticamente:

1. Aggiorna il numero Version: nell'intestazione del plugin
2. Effettua un commit e push nel ramo main
3. GitHub Actions rileva la modifica della versione e crea un nuovo rilascio con un ZIP scaricabile

Altri utenti possono quindi scaricare il ZIP dalla pagina Rilasci del tuo repository e installarlo come qualsiasi plugin WordPress.

Risoluzione dei Problemi

Il gateway non appare nel POS

• Controlla che il plugin sia attivato in WP Admin > Plugin
• Vai a WP Admin > WCPOS > Impostazioni > Checkout e assicurati che il gateway sia abilitato
• Verifica che WooCommerce sia installato e attivo

Il gateway appare nel checkout web

• Assicurati che $this->enabled = 'no'; sia impostato nel costruttore del gateway
• WCPOS sovrascrive questa impostazione per le richieste POS, quindi il gateway dovrebbe apparire solo nel POS

Gli ordini rimangono in 'In Elaborazione' invece di 'Completati'

• WooCommerce imposta lo stato dell'ordine in base ai tipi di prodotto. Gli ordini contenenti prodotti fisici rimangono in "In Elaborazione" — questo è il comportamento normale di WooCommerce. Solo gli ordini con esclusivamente prodotti virtuali o scaricabili sono segnati "Completati" automaticamente.

Risorse

• GitHub: woocommerce-gateway-template
• WooCommerce Payment Gateway API: WC_Payment_Gateway docs

Gateways di Esempio

Questi gateway esistenti sono stati costruiti con lo stesso approccio e sono buone referenze:

• Fattura via Email — Invia un'email di fattura in modo che il cliente possa pagare più tardi
• Checkout Web — Reindirizza al negozio online per il pagamento