Template per gateway

Il Template per gateway offre un punto di partenza per creare un gateway di pagamento personalizzato solo per POS. Genera un plugin WordPress funzionante con un singolo file PHP che si può installare e personalizzare in base alle proprie esigenze.

Funzionalità

Codice minimale

Un singolo file PHP con solo l’essenziale — facile da leggere e modificare

Solo POS

Disattivato per impostazione predefinita nel checkout web, attivato tramite le impostazioni di WCPOS

Configurazione automatizzata

Uno script shell gestisce tutte le sostituzioni dei segnaposto

Release GitHub

Esegui il push di un incremento di versione e GitHub Actions crea uno ZIP scaricabile

Per iniziare

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 GitHub per creare la tua copia.

2

Esegui lo script di configurazione

./create-gateway.sh

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

3

Installa il plugin

Sono disponibili due opzioni:

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

Opzione B — Comprimi e carica (la più semplice per la maggior parte degli utenti):

1. Comprimi la cartella generata in un file .zip
2. In WordPress, andare a Plugin > Aggiungi nuovo > Carica plugin
3. Scegliere il file ZIP e fare clic su Installa ora

4

Abilita in WCPOS

1. Andare a WP Admin > WCPOS > Impostazioni > Cassa
2. Trovare il nuovo gateway nell'elenco e abilitarlo

nota

Il gateway è disabilitato per impostazione predefinita nella normale cassa web. WCPOS controlla quali gateway vengono visualizzati nel POS tramite le proprie impostazioni.

Configurazione manuale

Se si preferisce non usare lo script, è possibile sostituire manualmente i segnaposto. Aprire ciascun file in un editor di testo e cercare e sostituire quanto segue:

Segnaposto	Cosa inserire	Esempio
{{GATEWAY_NAME}}	Nome visualizzato del gateway	Pagamento in contanti
{{GATEWAY_SLUG}}	Un identificatore sicuro per URL (minuscole, trattini)	pagamento-contanti
{{GATEWAY_DESCRIPTION}}	Breve descrizione del gateway	Accetta pagamenti in contanti in WCPOS
{{GATEWAY_DEFAULT_DESCRIPTION}}	Testo mostrato al cassiere al checkout	Paga in contanti al punto vendita
{{GITHUB_USERNAME}}	Il tuo nome utente GitHub	mariorossi
{{REPO_NAME}}	Il nome del tuo repository	gateway-pagamento-contanti
{{AUTHOR_NAME}}	Il tuo nome	Mario Rossi
{{GATEWAY_ID}}	Slug con trattini bassi al posto dei trattini	pagamento_contanti
{{GATEWAY_CLASS_NAME}}	Ogni parola con iniziale maiuscola, unite da trattini bassi	Pagamento_Contanti
{{GATEWAY_FUNCTION_PREFIX}}	Uguale all'ID del gateway	pagamento_contanti

Quindi rinomina wcpos-{{GATEWAY_SLUG}}.php in modo che corrisponda al tuo slug (ad esempio, wcpos-cash-payment.php).

consiglio

Lo script di configurazione deriva automaticamente GATEWAY_ID, GATEWAY_CLASS_NAME e GATEWAY_FUNCTION_PREFIX dal nome e dallo slug, quindi devi considerarli solo durante la configurazione manuale.

Come funziona

Il plugin generato registra una classe di gateway di pagamento WooCommerce. Ecco gli aspetti principali da conoscere:

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

Personalizzazione del gateway

Aggiunta di campi di pagamento

Se il gateway richiede un 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 contrassegna immediatamente gli ordini come pagati. Se il flusso di lavoro richiede un pagamento successivo (ad esempio una fattura), sostituisci payment_complete() con un aggiornamento di 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 aggiornare

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

1. Modificare wcpos-your-slug.php nella cartella generata
2. Aggiornare il numero Version: nell'intestazione del plugin (ad esempio, da 0.1.0 a 0.2.0)
3. Comprimere la cartella in un file zip e caricarla di nuovo tramite Plugin > Aggiungi nuovo > Carica plugin, oppure sostituire direttamente la cartella in wp-content/plugins/

consiglio

WordPress chiederà se si desidera sostituire il plugin esistente quando viene caricato un file zip con lo stesso nome del plugin: fare clic su Sostituisci quello attuale con quello caricato per aggiornare.

Rilasci automatici con GitHub

Se il gateway viene inviato a un repository GitHub, il modello include un flusso di lavoro GitHub Actions che crea automaticamente i rilasci:

1. Aggiornare il numero Version: nell'intestazione del plugin
2. Eseguire il commit e il push nel branch main
3. GitHub Actions rileva la modifica della versione e crea una nuova release con uno ZIP scaricabile

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

Risoluzione dei problemi

Il metodo di pagamento non appare nel POS

• Verifica che il plugin sia attivato in WP Admin > Plugin
• Vai a WP Admin > WCPOS > Impostazioni > Pagamento e assicurati che il metodo di pagamento sia abilitato
• Verifica che WooCommerce sia installato e attivo

Il metodo di pagamento viene visualizzato nel pagamento web

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

Gli ordini restano in 'In lavorazione' invece che in 'Completato'

• WooCommerce imposta lo stato dell'ordine in base ai tipi di prodotto. Gli ordini che contengono prodotti fisici restano in "In lavorazione": questo è il normale comportamento di WooCommerce. Solo gli ordini con prodotti esclusivamente virtuali o scaricabili vengono contrassegnati automaticamente come "Completato".

Requisiti

WCPOS: Versione Pro richiesta per il checkout POS

WordPress: WordPress con WooCommerce installato

PHP: Conoscenza di base di PHP per personalizzare il gateway

Risorse

• GitHub: woocommerce-gateway-template
• API del gateway di pagamento WooCommerce: documentazione WC_Payment_Gateway

Gateway di esempio

Questi gateway esistenti sono stati creati con lo stesso approccio e sono buoni riferimenti:

• Fattura via email — Invia una fattura via email affinché il cliente possa pagare in seguito
• Checkout web — Reindirizza al negozio web per il pagamento