Connettere Shopify nel 2026

Dal 1 gennaio 2026 Shopify ha ritirato le Custom App legacy per i nuovi store: il bottone "Sviluppa app personalizzate legacy" è ancora visibile, ma per un account merchant normale (non dev store, non Plus, non partner store) cliccarlo non fa nulla.

Il nuovo flusso è quello che usa anche Checkify: il merchant crea una dev-app personale dentro il proprio Shopify Dev Dashboard, ci dà Client ID + Client Secret, e noi avviamo l'OAuth verso il SUO admin per ottenere il token di accesso. ~3 minuti totali.

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 2026 è 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

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 automaticamente lo script tag sul theme attivo del tuo Shopify — non devi toccare theme.liquid
• 🌐 Provisiona il tuo subdomain tuo-slug.wooshpayment.com (DNS + SSL Vercel)
• ✨ Ti porta a completare l'onboarding (brand, spedizioni, payments)

Dopo il setup, ogni click su Checkout dal carrello Shopify reindirizza al tuo checkout brandizzato tuo-slug.wooshpayment.com/checkout/.... Gli ordini pagati su WooshPayment vengono creati come ordini reali su Shopify con payment_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ì. Nel nuovo Dev Dashboard 2026 quella checkbox è 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 2026 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?

Solo se il tuo store era già configurato per le Custom App legacy prima del 1 gennaio 2026 (dev store, partner store, store trasferiti). Per i merchant normali del 2026 il bottone "Consenti lo sviluppo di app personalizzate legacy" è inerte. Il flusso Dev Dashboard è l'unico che funziona.

---

Hai bisogno di una mano? Apri un ticket di supporto o scrivi nella chat in basso a destra della dashboard.