Guida WooshPayment

WooshPayment sostituisce il checkout standard di Shopify con una pagina one-page brandizzata col tuo dominio (es. checkout.tuosito.com). Apple Pay e Google Pay funzionano nativamente, fino a +18% di conversione mobile nei nostri test pilota.

I 4 step per andare live

1. Crea un account. Vai su wooshpayment.com/signup, conferma l'email. La modalità Demo è gratis: configuri tutto e paghi €99/mese solo quando attivi il checkout live.
2. Collega Shopify. Genera un Admin API token dal tuo Shopify Admin e incollalo in Dashboard → Integrazioni. Guida dettagliata nell<anchor>Articolo 2</anchor>.
3. Personalizza il checkout. Colori, logo, testi — Dashboard → Checkout. Vedi l<anchor>Articolo 3</anchor>.
4. Installa lo script tag. Dalla pagina Integrazioni clicca "Installa script tag". È un click solo, WooshPayment si occupa del resto.

Per attivare i pixel di marketing (Meta CAPI, TikTok, GA4) leggi l<anchorPixel>Articolo 4</anchorPixel>. Per un dominio personalizzato tipo <code>checkout.tuosito.com</code>, lArticolo 5.

1. Apri il pannello custom app in Shopify

1. Entra in Shopify Admin
2. Apri Settings → Apps and sales channels
3. Clicca Develop apps (se è la prima volta dovrai abilitarlo)
4. Clicca Create an app, dai un nome (es. "WooshPayment")

2. Configura gli Admin API scopes

Nella tab Configuration, sezione Admin API integration, abilita questi scope:

• read_orders — leggere gli ordini esistenti
• write_orders — creare l'ordine su Shopify dopo il pagamento
• read_checkouts e write_checkouts — gestire i carrelli
• read_products — recuperare i prodotti del carrello
• read_customers — collegare l'ordine al cliente esistente se già registrato
• write_script_tags e read_script_tags — installare lo script che intercetta il checkout

3. Installa l'app e genera il token

1. Tab API credentials → Install app
2. Conferma — Shopify genera un Admin API access token (inizia per shpat_)
3. Copialo subito! Shopify lo mostra una sola volta. Se lo perdi, dovrai disinstallare e reinstallare l'app.

4. Incolla nel dashboard WooshPayment

Apri Dashboard → Integrazioni, sezione Shopify. Incolla il token e il dominio del tuo store (es. mio-store.myshopify.com) e clicca Salva e verifica. Il dashboard fa una chiamata di test: se va a buon fine vedi il badge verde "Connesso".

Troubleshooting

• "Scopes mancanti": torna in Shopify Admin → Configuration, aggiungi lo scope mancante, clicca Save, poi Install di nuovo. Genera un nuovo token e re-incollalo.
• "Invalid access token": hai probabilmente disinstallato e reinstallato l'app. Il vecchio token è morto, genera uno nuovo.
• "Store domain not found": usa il dominio .myshopify.com, non il dominio custom del tuo store.

Tutta la personalizzazione vive in Dashboard → Checkout. Le modifiche sono immediate: salvi e il prossimo cliente vede già le tue scelte.

Brand color

Usa un colore esadecimale (es. #3b5bdb). Sarà applicato a:

• Bottone "Acquista ora"
• Link e accenti grafici
• Header del checkout
• Spinner e stati di caricamento

Logo

• Formato: PNG o SVG (preferibile)
• Sfondo: trasparente — il checkout è su sfondo bianco
• Dimensioni consigliate: almeno 240px di larghezza, max 1MB
• Altezza: verrà ridimensionato automaticamente a circa 36px nell'header mobile, 44px desktop

Testi customizzabili

Puoi sovrascrivere:

• Header — appare sopra il riepilogo carrello (es. "Spedizione gratis sopra €50" oppure "Reso facile entro 30 giorni")
• Footer — sotto i metodi di pagamento (es. info su spedizione gratuita o garanzia 30gg)
• Trust badges — linea di testo extra accanto a "Pagamento sicuro"

Preview live

Il pannello laterale destro nel dashboard mostra il checkout in tempo reale. Switcha tra Desktop e Mobile con il toggle in alto. Test sempre la modalità Mobile: oltre il 70% degli ordini arriva da telefono.

Suggerimenti UX

• Usa un logo trasparente: gli sfondi colorati stonano col checkout bianco
• Il brand color deve contrastare bene col bianco (non giallo, non azzurrino pastello)
• I testi custom devono essere brevi — 1 riga su mobile, max 2 desktop
• Non scrivere testi promozionali sull'header se non sono veri: ammazza la fiducia

Tutti i pixel si configurano in Dashboard → Integrazioni, sezione Pixel & Analytics. Le chiavi private vengono cifrate at-rest e usate solo lato server: non vengono mai inviate al browser del cliente.

Meta (Facebook) Pixel + CAPI

A cosa serve: tracciare InitiateCheckout e Purchase nel tuo Business Manager per Ads.

• Pixel ID (pubblico): 15-16 cifre, lo trovi in Events Manager → Data sources → il tuo pixel → ID
• CAPI Access Token (avanzato): Events Manager → Settings → Conversions API → Generate access token. Tienilo segreto, è una chiave.

TikTok Pixel + Events API

A cosa serve: ottimizzare campagne TikTok Ads basate su acquisti reali.

• Pixel ID (pubblico): TikTok Events Manager → Tools → Pixel → Pixel Code → 19-20 caratteri tipo CXXXXXXXXXXXXXXXXXX
• Events API Access Token (avanzato): nella stessa pagina, tab "Events API"

Google Analytics 4

A cosa serve: il bread & butter delle analytics. Eventi begin_checkout e purchase.

• Measurement ID (pubblico): GA4 → Admin → Data Streams → Web → il tuo stream → ID (formato G-XXXXXXXXXX)
• API Secret (opzionale, server-side via Measurement Protocol): stessa pagina, sezione "Measurement Protocol API secrets"

Perché conviene

Avere il checkout su checkout.tuosito.com invece di tuo-slug.wooshpayment.com:

• Aumenta la fiducia del cliente (resta sul "tuo" sito)
• Conversioni +5-15% mediamente (dati internal WooshPayment)
• Migliora l'attribuzione cookie di prima parte (meno problemi con iOS 14+ e Safari ITP)

Setup in 4 step

1. Vai in Dashboard → Settings → Dominio personalizzato e inserisci il sottodominio che vuoi usare (es. checkout.tuosito.com).
2. Apri il pannello DNS del tuo registrar (GoDaddy, Cloudflare, Aruba, OVH...) e aggiungi un record CNAME:

   Tipo:   CNAME
   Host:   checkout
   Punta a: cname.vercel-dns.com
   TTL:    3600 (o auto)

3. Torna sul dashboard e clicca Verifica. Se vedi "DNS rilevato", sei quasi pronto.
4. Il certificato SSL (Let's Encrypt) viene emesso automaticamente entro pochi minuti. Quando lo stato diventa "Attivo", il dominio è live.

Troubleshooting

• Propagazione DNS lenta: normale, può richiedere fino a 24h. Solitamente è online in 10-30 minuti. Verifica con dig checkout.tuosito.com CNAME da terminale.
• TTL troppo alto: se avevi un vecchio record con TTL di 24h, dovrai aspettare. La prossima volta usa TTL 3600 o auto.
• "Domain already in use": qualcun altro lo ha già reclamato su Vercel. Scrivici a support@wooshpayment.com.
• SSL non si attiva dopo 1h: probabile errore CAA record sul dominio apex che blocca Let's Encrypt. Aggiungi 0 issue "letsencrypt.org".

Come rimborsare

1. Vai in Dashboard → Ordini
2. Clicca sull'ordine che vuoi rimborsare
3. In alto a destra clicca Rimborsa
4. Conferma nella modal. Il bottone si disabilita finché l'operazione è in corso.

Cosa succede dietro le quinte

• Whop: emette il rimborso sulla carta del cliente (full refund)
• Shopify: annulla l'ordine e marca come "refunded"
• Inventario: i prodotti rientrano in stock automaticamente (restock = true)
• Email cliente: il cliente riceve una conferma automatica del rimborso

Refund parziale

Al momento WooshPayment supporta solo il refund totale. Per un rimborso parziale (es. solo 1 prodotto su 3) procedi così:

1. Rimborsa l'ordine completo da WooshPayment
2. Apri Shopify, ricrea un ordine manuale per i prodotti che il cliente vuole tenere
3. Manda al cliente il link al nuovo ordine se vuole ripagare

Timeline

• Lato WooshPayment/Whop: il rimborso è istantaneo dal punto di vista nostro
• Lato banca cliente: 5-10 giorni lavorativi per vedere il riaccredito sulla carta
• Email di conferma: entro 5 minuti dall'azione

"Apple Pay non è visibile sul checkout"

Apple Pay richiede che il dominio del tuo checkout sia registrato su Whop come payment domain. Per i merchant nuovi questo è automatico (Sprint 4). Per i merchant legacy potrebbe servire un setup manuale: contattaci e ti registriamo il dominio in pochi minuti, oppure consulta il runbook interno work/docs/apple-pay-manual.md.

Verifica anche: il cliente sta usando Safari su iOS/macOS o Chrome su macOS con Apple Pay configurato. Apple Pay non appare su Chrome Windows o Android (Google Pay sì).

"Il cliente clicca Check out su Shopify e non si apre nulla"

1. Vai in Dashboard → Integrazioni, verifica che il badge Script tag su Shopify sia verde "Installato".
2. Se non lo è, clicca Installa script tag. Se è installato ma non funziona, clicca Reinstalla (rimuove eventuali duplicati).
3. Se il problema persiste, controlla la Console del browser (F12) sul tuo store: errori JS lì spesso indicano theme che blocca lo script tag.

"L'email di conferma ordine non arriva al cliente"

• Chiedi al cliente di controllare la cartella spam/promozioni
• Verifica che l'email del cliente sia corretta in Ordini
• Se più clienti riportano il problema, potrebbe essere un'issue con DKIM/DMARC del nostro provider Resend. Scrivici subito, è un problema di piattaforma e lo risolviamo noi.

"L'ordine non si sincronizza su Shopify"

1. Vai sull'ordine nel dashboard WooshPayment e verifica lo stato del webhook
2. Se vedi "Failed" o "Pending", il problema è che il token Shopify potrebbe essere scaduto. Rigenerane uno (Articolo 2) e re-inseriscilo.
3. Verifica anche che gli scope write_orders siano attivi sull'app Shopify

"I pixel marketing non vedono gli eventi"

• Verifica che il Pixel ID sia corretto (pubblico, non il nome del pixel)
• Usa il Test Event Manager del provider (Meta, TikTok, ecc.) per vedere se l'evento arriva
• Fai un ordine di test da incognito (estensioni adblock falsano il test client-side)
• Per Meta CAPI e TikTok CAPI, ricontrolla che l<strong>access token</strong> non sia scaduto

"L'importo addebitato al cliente è sbagliato"

Questo bug è stato risolto nello Sprint 5: ora il prezzo mostrato al cliente coincide sempre con quanto addebitato. Se vedi ancora discrepanze, è urgente — scrivici subito a support@wooshpayment.com con l'order ID e ti rispondiamo in giornata.

"Lo stato dell'ordine è 'pending' da troppo tempo"

• Sopra le 24h è anomalo. Il pagamento è andato a buon fine ma il webhook Whop ha mancato il colpo.
• Vai sull'ordine e clicca Aggiorna stato per forzare un refresh manuale via API.
• Se ancora pending, scrivici con l'order ID.

Base URL: https://api.wooshpayment.com

POST /api/checkout/create

Crea una nuova sessione di checkout. Non richiede auth — protetta da rate limit.

curl -s -X POST https://api.wooshpayment.com/api/checkout/create \
  -H "Content-Type: application/json" \
  -d '{
    "shop": "woopay-test-store.myshopify.com",
    "cartToken": "abc123",
    "items": [
      { "id": 1, "title": "T-shirt", "variant_id": 1, "quantity": 1, "price": 1000 }
    ],
    "totalPrice": 1000,
    "currency": "USD"
  }'

pageHelp.articles.apiReference.createResponse

GET /api/checkout/session/:token

Recupera lo stato di una sessione (usata dal frontend del checkout per polling).

curl -s https://api.wooshpayment.com/api/checkout/session/ch_xxx

POST /api/checkout/:token/refresh-status

Forza un refresh dello stato di una sessione direttamente da Whop. Usalo se sospetti che un webhook sia stato perso.

curl -s -X POST https://api.wooshpayment.com/api/checkout/ch_xxx/refresh-status

Endpoint merchant (autenticati)

Tutte le route /api/merchant/* richiedono un JWT in header. Il token lo ottieni dal login del dashboard:

curl -s https://api.wooshpayment.com/api/merchant/me \
  -H "Authorization: Bearer <jwt>"

Rate limits

• Endpoint pubblici: 60 richieste/minuto/IP
• Endpoint merchant: 300 richieste/minuto/merchant
• Webhook inbound: nessun limite (validati con HMAC)

Quando superi il limite ricevi 429 Too Many Requests.

Webhook outbound

Per la lista completa degli endpoint, consulta la sorgente in apps/api/src/routes/ (open source coming soon) o scrivici a support@wooshpayment.com.