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, conversioni in media +18% sul mobile.

I 4 step per andare live

1. Crea un account. Vai su wooshpayment.com/signup, conferma l'email. Il piano Starter è gratis fino a 100 ordini/mese.
2. Collega Shopify. Genera un Admin API token dal tuo Shopify Admin e incollalo in Dashboard → Integrazioni. Guida dettagliata nell'Articolo 2.
3. Personalizza il checkout. Colori, logo, testi — Dashboard → Checkout. Vedi l'Articolo 3.
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, TikTok, GA4, Klaviyo...) leggi l'Articolo 4. Per un dominio personalizzato tipo checkout.tuosito.com, l'Articolo 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. "Mancano 2 minuti per ricevere lo sconto del 10%")
• 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"

Pinterest Tag + Conversions API

A cosa serve: attribuire acquisti ai Pin che hanno generato il traffico.

• Tag ID (pubblico): Pinterest Business → Conversions → Tag Manager
• Ad Account ID + Access Token (avanzato): nella stessa area, sotto "Conversions API"

Snapchat Pixel + CAPI

A cosa serve: tracciare PURCHASE per le campagne Snap Ads.

• Pixel ID (pubblico): Snap Ads Manager → Events Manager → il tuo pixel → ID (UUID tipo xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
• Conversions API Token (avanzato): nella stessa pagina del pixel

Klaviyo

A cosa serve: attivare flussi email "Placed Order", segmenti per RFM, abbandoni avanzati.

• Public API Key (sempre obbligatorio): Klaviyo → Account → Settings → API Keys → Public API Key (6 caratteri)
• Private API Key (per server-side, fortemente consigliata): stessa pagina, sezione "Private API Keys". Crea una key con scope "Full Access" o almeno "Events: Write". Inizia per pk_.

Omnisend

A cosa serve: ricevere gli eventi "placed order" sul tuo account Omnisend per automation.

• Brand ID (pubblico): Omnisend → Store settings → General
• API Key: Omnisend → Store settings → Integrations & API → API keys

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 Klaviyo e Meta CAPI, ricontrolla che la private/access token non sia scaduta

"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"
  }'

Risponde con { token, url }. L'url è il link al checkout brandizzato a cui rediregere il cliente.

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 .