Guida WooshPayment

WooshPayment sostituisce il checkout standard di Shopify o WooCommerce con una pagina one-page brandizzata col tuo dominio (es. checkout.tuosito.com). I pagamenti card passano da Whop; i wallet appaiono solo quando Whop, dominio checkout, browser e device sono idonei.

I 4 step prima del traffico

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 l'intercettazione checkout.
2. Collega lo store. Shopify: crea una dev-app nel tuo Shopify Dev Dashboard, incolla Client ID + Secret in Dashboard → Impostazioni e autorizza l'installazione. WooCommerce: installa il plugin ufficiale, genera API REST read/write e collega lo store da Dashboard → Integrazioni. Guida Shopify nell<anchor>Articolo 2</anchor>, guida Woo nei docs.
3. Personalizza il checkout. Colori, logo, testi — Dashboard → Checkout. Vedi l<anchor>Articolo 3</anchor>.
4. Verifica interceptor checkout. Verifica dal tuo store in incognito che il click su Checkout apra WooshPayment: su Shopify controlla OAuth/ScriptTag da Dashboard → Impostazioni o Script tag debug; su WooCommerce controlla plugin ufficiale attivo e ultimo checkout intercettato in Dashboard → Integrazioni.

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. Crea una dev-app nel Shopify Dev Dashboard

1. Entra in Shopify Admin → Settings → Apps
2. Apri Develop apps e clicca Build apps in Dev Dashboard
3. Clicca Create app, scegli Start from Dev Dashboard e dai nome WooshPayment
4. Apri Versions → Create version

2. Configura URL e scope

In URLs imposta App URL su https://wooshpayment.com. In Accesso incolla questi scope nella textarea Ambiti:

• 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. Copia Client ID + Client Secret

1. Vai nella tab Settings della dev-app
2. Copia il Client ID
3. Rivela e copia il Client Secret. Se l'hai perso, usa Rotate secret.

4. Incolla in WooshPayment e autorizza

Apri Dashboard → Impostazioni, sezione Shopify. Incolla dominio, Client ID e Client Secret e clicca Apri autorizzazione Shopify. Shopify mostra la schermata Install: conferma e torni su WooshPayment con ScriptTag installato.

Troubleshooting

• HMAC / secret errato: ruota il Client Secret nella dev-app e incolla quello nuovo in WooshPayment.
• Redirect URL errato: deve essere esattamente https://api.wooshpayment.com/auth/shopify/callback.
• App non rilasciata: crea e rilascia una versione prima di cliccare Connetti 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. Non mandare traffico finché dominio e ordine pilota non sono verificati. 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 hello@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)
• Store: annulla l'ordine su Shopify o WooCommerce quando l'integrazione è connessa
• Inventario: il riallineamento stock segue la cancellazione ordine sulla piattaforma collegata
• 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 il tuo store, 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 viene registrato dopo la conferma di Whop
• Lato banca cliente: 5-10 giorni lavorativi per vedere il riaccredito sulla carta
• Email di conferma: accettata dal provider email dopo l'evento refund

"Apple Pay non è visibile sul checkout"

Apple Pay richiede che il dominio del tuo checkout sia registrato su Whop come payment domain. Il tentativo automatico è best-effort: prima di mandare traffico, verifica nel Whop dashboard → Settings → Checkout → Apple Pay for embedded checkout che your-slug.wooshpayment.com o il dominio custom sia presente. Se manca, aggiungilo manualmente seguendo la guida Apple Pay.

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 può apparire solo quando Whop, browser, device e dominio lo supportano.

"Il cliente clicca Check out sullo store e non si apre nulla"

1. Shopify: apri Dashboard → Impostazioni e verifica che OAuth sia completato; se il redirect non parte usa Script tag debug. WooCommerce: apri Dashboard → Integrazioni e verifica plugin ufficiale attivo e ultimo checkout intercettato recente.
2. Shopify: se lo ScriptTag non è installato, completa di nuovo l'autorizzazione o usa la guida Script tag debug. WooCommerce: aggiorna il plugin, salva di nuovo le API REST e fai un test da carrello.
3. Se il problema persiste, controlla la Console del browser (F12) sul tuo store: errori JS o cache/theme possono bloccare l'interceptor.

"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 sullo store"

1. Vai sull'ordine nel dashboard WooshPayment e verifica stato webhook, Ordine store e ultimo tentativo di sync.
2. Shopify: controlla OAuth/ScriptTag e scope write_orders da Dashboard → Impostazioni. WooCommerce: controlla plugin ufficiale, API REST read/write e URL store in Dashboard → Integrazioni.
3. Se Whop è amber o manca il webhook secret, completa Integrazioni: senza firma webhook gli ordini non vengono creati in tempo reale.

"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 hello@wooshpayment.com con l'order ID e lo trattiamo come priorità.

"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 i campi token e url. L<code>url</code> è il link al checkout brandizzato a cui redirigere 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 hello@wooshpayment.com.