Connettere Shopify con Dev Dashboard + OAuth

WooshPayment non usa il vecchio percorso "incolla un token Admin API e basta" per i nuovi merchant. Il percorso supportato è una dev-app personale nel tuo Shopify Dev Dashboard, installata via OAuth authorization-code grant come app standalone.

Tu ci dai Client ID + Client Secret, noi avviamo l'OAuth verso il TUO admin per ottenere il token di accesso. Non considerarlo concluso finche' non hai autorizzato l'app, verificato lo ScriptTag e completato il test reale dal carrello live.

Prerequisiti

• Accesso da owner o staff abilitato alla gestione delle app sul tuo store Shopify
• Il tuo dominio store (es. mio-store.myshopify.com)
• Un account WooshPayment attivo

---

1. Apri il Dev Dashboard dentro Shopify

1. Vai su https://mio-store.myshopify.com/admin
2. Click sull'icona ⚙ Impostazioni in basso a sinistra (o , da tastiera)
3. Nella colonna sinistra, click su App
4. In alto a destra, click Sviluppo app
5. Nella card Sviluppa e gestisci le app nella tua Dev Dashboard, click sul bottone scuro Sviluppa app nella Dev Dashboard

Si apre il Dev Dashboard di Shopify (in una nuova tab o overlay).

2. Crea una nuova app nel Dev Dashboard

1. Dentro il Dev Dashboard, click sul bottone Crea app in alto a destra
2. Atterri sulla pagina dedicata "Crea un'app", con due card affiancate:
   • Inizia con lo strumento CLI di Shopify (per developer avanzati con CLI Shopify locale)
   • Inizia dalla Dev Dashboard (più semplice, nessun CLI richiesto) → scegli questa
3. Nel campo Nome app scrivi WooshPayment (o un nome che riconosci)
4. Click Crea

Vieni rediretto sulla pagina dell'app appena creata. Dalla sidebar dell'app puoi accedere a Monitoraggio, Log, Versioni, Impostazioni.

3. Crea una versione: configura URL e disabilita l'embed

Dalla sezione Versioni dell'app, click su Crea versione. Si apre la pagina dedicata Crea versione (non una tab, una pagina intera):

1. Sezione URL → URL app: incolla https://wooshpayment.com
2. Subito sotto, trova la checkbox Incorpora l'app nel pannello di controllo Shopify — è spuntata di default. DISATTIVALA.
3. Lascia vuoto il campo URL preferenze (facoltativo)

4. Configura gli ambiti di accesso

Scorri in basso, sezione Accesso:

1. Ambiti: nel Dev Dashboard attuale è una textarea singola con gli scope separati da virgola (non checkbox individuali). Incolla esattamente:

   read_orders,write_orders,read_checkouts,write_checkouts,read_products,read_customers,read_script_tags,write_script_tags

   Sono 8 ambiti e fanno:

   Ambito tecnico	A cosa serve
   read_orders	Leggere gli ordini esistenti
   write_orders	Creare l'ordine dopo pagamento confermato
   read_checkouts	Recuperare sessione checkout in corso
   write_checkouts	Aggiornare la sessione checkout
   read_products	Leggere catalogo, prezzi, varianti
   read_customers	Auto-fill indirizzo per clienti già registrati
   read_script_tags	Verificare lo script tag
   write_script_tags	Installare lo script che intercetta il bottone Checkout

2. Ambiti facoltativi: lascia vuoto

3. Usa flusso di installazione legacy: lascia NON spuntato

4. URL di reindirizzamento (in fondo al form, dentro la stessa sezione Accesso): incolla https://api.wooshpayment.com/auth/shopify/callback

5. Rilascia la versione

1. In basso a destra della pagina Crea versione, click sul bottone Rilascia
2. Si apre il modal Rilasciare questa nuova versione?
3. (Facoltativo) Compila Nome versione e Messaggio della versione — puoi anche lasciare entrambi vuoti, Shopify auto-genera un nome
4. Click sul bottone Rilascia nel modal

Aspetta il toast di conferma. La nuova versione diventa Attiva.

6. Copia ID client + Segreto

Dalla sidebar dell'app, click su Impostazioni:

1. Cerca la card Credenziali
2. ID client: copia il valore (visibile per intero, ~32 caratteri) cliccando l'icona 📋 a destra
3. Segreto: è mascherato. Click sull'icona 👁 per rivelarlo, poi 📋 per copiarlo
   • Se ti viene chiesto e l'hai già usato, click sul bottone Ruota per generarne uno nuovo (il vecchio diventa invalido)

7. Incolla in WooshPayment e completa l'install

1. Apri https://wooshpayment.com/onboarding in un'altra tab
2. Step Piattaforma → Shopify, scorri al sub-step 3 (Incolla Client ID + Secret)
3. Compila:
   • Dominio Shopify: mio-store.myshopify.com
   • Client ID: l'ID client copiato al punto 6
   • Client Secret: il Segreto copiato al punto 6
4. Click Connetti store

Vieni rediretto su Shopify nella schermata Install app. Vedi un banner "This app hasn't been reviewed" — è normale per le dev-app non in App Store.

5. Click Install nel pannello Shopify
6. Torni automaticamente su WooshPayment nello step Brand dell'onboarding

Il ritorno allo step Brand conferma che l'OAuth è riuscito. Non è ancora un via libera al traffico: completa piano attivo, Whop/COD e almeno un ordine pilota pagato dal carrello live prima di lanciare ads.

Cosa fa WooshPayment a questo punto

• 🔐 Salva Client ID + Secret cifrati (AES-256-GCM) sul nostro DB
• 🔄 Riceve il token OAuth e lo salva (sempre cifrato)
• 📜 Installa lo script tag sul theme attivo del tuo Shopify e richiede un test reale dal carrello live prima del traffico
• 🌐 Provisiona il tuo subdomain tuo-slug.wooshpayment.com (DNS + SSL Vercel)
• ✨ Ti porta a completare l'onboarding (brand, spedizioni, payments)

Dopo il setup, verifica dal carrello Shopify pubblicato che il click su Checkout reindirizzi al tuo checkout brandizzato tuo-slug.wooshpayment.com/checkout/.... Se il tema live non carica ScriptTag o il canale è headless/custom, non mandare traffico: serve supporto o un app embed dedicato. Gli ordini pagati su WooshPayment vengono creati come ordini reali su Shopify con financial_status: paid.

Troubleshooting

"Client ID o Secret non valido"

Verifica nell'ordine:

1. Hai cliccato Rilascia al punto 5? Senza una versione rilasciata, l'OAuth non parte.
2. Hai copiato l'ID client per intero? Niente spazi prima/dopo.
3. Il Segreto è giusto? Se hai chiuso la tab senza copiarlo, vai su Impostazioni → Credenziali → Ruota per generarne uno nuovo.

La checkbox "Incorpora l'app nel pannello di controllo Shopify" è SPUNTATA di default

Sì, può essere attiva di default. Devi disattivarla manualmente prima di rilasciare la versione, oppure l'OAuth fallisce (Shopify tenta di incorporare WooshPayment in iframe e noi non siamo un'app embedded).

Shopify dice "Embed app must be enabled" / "Incorpora app deve essere attivo"

Hai lasciato la checkbox Incorpora l'app nel pannello di controllo Shopify spuntata al punto 3. Apri Versioni → Crea versione, disattivala, rilascia una nuova versione, poi ri-click Connetti store nella dashboard WooshPayment.

Vedo solo "URL app" e "URL di reindirizzamento" separati, non c'è una sezione "Access" inglese

Normale. Nel Dev Dashboard in italiano la sezione è chiamata Accesso (non "Access"). URL di reindirizzamento si trova in fondo al form Crea versione, dentro la sezione Accesso, dopo la textarea Ambiti — non è in una sezione separata.

Il bottone "Install" su Shopify non si attiva

Spesso significa scope mancanti nella textarea Ambiti. Apri Versioni → Crea versione, controlla che tutti gli 8 ambiti siano nella textarea separati da virgola, rilascia di nuovo, ripeti il punto 7.

Voglio rimuovere l'app

1. Vai su Shopify Dev Dashboard → la tua app WooshPayment
2. Sidebar Impostazioni → in fondo, bottone Elimina app

Il token diventa invalido immediatamente, lo script tag viene rimosso dal theme, l'integrazione su WooshPayment passa in stato "non connesso".

Posso usare il vecchio metodo (token shpat_) invece?

No per nuove connessioni WooshPayment. Se hai una connessione storica già funzionante, puoi lasciarla attiva; per nuovi store o riconnessioni usa Dev Dashboard + OAuth.

---

Hai bisogno di una mano? Scrivi a hello@wooshpayment.com o usa la chat in basso a destra della dashboard.