# 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à[​](#features "Collegamento diretto a 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[​](#getting-started "Collegamento diretto a 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](https://github.com/wcpos/woocommerce-gateway-template) 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[​](#manual-setup "Collegamento diretto a 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[​](#how-it-works "Collegamento diretto a 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[​](#customising-your-gateway "Collegamento diretto a Personalizzazione del gateway")

### Aggiunta di campi di pagamento[​](#adding-payment-fields "Collegamento diretto a 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[​](#changing-payment-behaviour "Collegamento diretto a 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[​](#making-changes-and-updating "Collegamento diretto a 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[​](#automated-releases-with-github "Collegamento diretto a 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[​](#troubleshooting "Collegamento diretto a 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[​](#requirements "Collegamento diretto a 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[​](#resources "Collegamento diretto a Risorse")

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

### Gateway di esempio[​](#example-gateways "Collegamento diretto a Gateway di esempio")

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

* **[Fattura via email](/it/payment/gateways/email-invoice.md)** — Invia una fattura via email affinché il cliente possa pagare in seguito
* **[Checkout web](/it/payment/gateways/web-checkout.md)** — Reindirizza al negozio web per il pagamento