# WooCommerce

> Un metodo di pagamento per WooCommerce: bitcoin e USDC/USDT dritti nel tuo wallet, e un webhook firmato segna l’ordine come pagato.

Il plugin Perly Pay aggiunge le crypto al checkout classico e al blocco Checkout. Ogni ordine diventa una fattura Perly Pay; l’acquirente la paga sopra il tuo negozio o su una pagina a parte; un webhook firmato segna l’ordine come pagato. WordPress 6.5+, WooCommerce 8.6+, PHP 8.1+. Niente da installare sul server: l’[SDK PHP](https://pay.perly.io/docs/sdks.md) è già incluso.

> **Nota:** Le fatture sono in USD o EUR. In un negozio con un’altra valuta il metodo di pagamento viene nascosto e le sue impostazioni spiegano perché.

## Installazione

1. **Prendi lo zip** — Il plugin è in arrivo su WordPress.org. Finché non c’è, [scrivici](https://pay.perly.io/it/contact) per avere `perly-pay-woocommerce.zip`.
2. **Installalo** — In WordPress: Plugin → Aggiungi nuovo plugin → Carica plugin, scegli lo zip e attivalo. WooCommerce deve essere attivo.
3. **Apri le impostazioni** — WooCommerce → Impostazioni → Pagamenti → **Perly Pay**.

## Configurazione

| Campo | Cosa inserire |
| --- | --- |
| Secret key | Dashboard → Developers → API keys. `sk_test_…` per la [modalità test](https://pay.perly.io/docs/test-mode.md), `sk_live_…` per il denaro reale. Le impostazioni mostrano in che modalità sei. |
| Webhook signing secret | `whsec_…`. **Set up webhook** lo compila da solo. |
| Payment page | **Overlay** apre il checkout sopra il tuo negozio (pay.js). **Redirect** porta l’acquirente alla sua pagina. Sui telefoni si apre sempre la pagina. |
| Status when paid | Quello che decide WooCommerce (In lavorazione; Completato per i download), sempre In lavorazione o sempre Completato. |
| Title, Description | Quello che vedono gli acquirenti al checkout. |
| Debug log | Eventi ed errori in WooCommerce → Stato → Log. Mai chiavi, segreti o dati degli acquirenti. |

1. **Incolla la chiave** — E premi **Test connection**: vedrai se la chiave funziona, la sua modalità e se Perly Pay ha il webhook di questo negozio.
2. **Configura il webhook** — Premi **Set up webhook**. Aggiunge l’indirizzo del tuo negozio (è sopra i pulsanti, `…/wp-json/perly-pay/v1/webhook`) a Perly Pay e salva il segreto. Oppure aggiungilo tu in Developers → Webhooks e incolla il segreto.
3. **Consenti l’overlay** — In Dashboard → Settings, aggiungi l’indirizzo del tuo negozio in **Sites that may embed the checkout**. Senza questo, l’overlay propone di aprire il checkout in una nuova scheda.
4. **Attivalo** — Spunta **Take crypto with Perly Pay** e salva.

## Provalo

Con una chiave `sk_test_…`, fai un ordine nel tuo negozio e scegli Perly Pay. L’ordine resta **In attesa di pagamento**. Paga la fattura con monete di test o via API; il suo id è nelle note dell’ordine:

```bash
curl -X POST https://pay.perly.io/api/v1/invoices/inv_…/simulate \
  -H "Authorization: Bearer $PERLY_PAY_SECRET_KEY" -H "Content-Type: application/json" -d '{}'
```

In pochi secondi l’ordine passa a **In lavorazione**, con una nota: la rete, l’importo e un link alla transazione. `{"outcome":"short"}` e `{"outcome":"over"}` provano gli altri casi, una volta scelta la moneta nella pagina della fattura.

## Come gli ordini seguono i pagamenti

| In Perly Pay | L’ordine |
| --- | --- |
| Pagata, mittente controllato (`invoice.fulfilled`) | Pagato: lo stato scelto, magazzino ridotto, email all’acquirente. Una nota per ogni trasferimento e la sua transazione. |
| Vista, pagata in parte, pagata e ancora in verifica | Una nota. Resta in attesa. |
| Trattenuta per [verifica](https://pay.perly.io/docs/screening.md) | In sospeso, con il motivo. Decidi in Perly Pay. |
| Scaduta o annullata, senza alcun pagamento | Annullato. |
| Scaduta, pagata in parte | In sospeso: rimborsa o accetta in Perly Pay. |
| Rimborsata | Rimborsato per intero, o una nota per la parte. |

Ogni evento si applica una volta, all’ordine per cui è stato creato, e uno «scaduto» tardivo non annulla mai un pagamento. Se l’acquirente torna alla pagina di ringraziamento prima del webhook, il plugin interroga l’API e aggiorna subito l’ordine.

## Rimborsi

Rimborsa come sempre, dalla pagina dell’ordine: il plugin apre un [rimborso](https://pay.perly.io/docs/refunds.md) in Perly Pay nella moneta con cui si è pagato (una parte se è parziale). Perly Pay chiede all’acquirente un indirizzo via email e lo controlla; le note dell’ordine ti dicono cosa inviare e dove. Lo invii dal tuo wallet e incolli l’id della transazione in Perly Pay: Perly Pay non tiene mai il denaro.

## Andare live

- Attiva la modalità live in Perly Pay e collega le chiavi pubbliche del tuo wallet.
- Incolla una chiave `sk_live_…`. Chiavi e webhook live sono separati da quelli di test: premi di nuovo **Set up webhook**.
- Aggiungi l’indirizzo https del tuo negozio live in **Sites that may embed the checkout** in modalità live.
- Fai un piccolo ordine reale e rimborsalo.