WWooshPayment docs
Integrazione store

Integrazione Shopify

Connetti Shopify a WooshPayment con Dev Dashboard + OAuth. ScriptTag installato, test carrello live obbligatorio, ordini sincronizzati, scope minimi.

4 min di lettura

L'integrazione Shopify usa una dev-app creata nel tuo Shopify Dev Dashboard più OAuth. Tu incolli in WooshPayment Client ID + Client Secret, autorizzi l'app nel tuo admin Shopify, e noi installiamo lo ScriptTag che intercetta il bottone "Checkout" e lo redirige sul tuo checkout WooshPayment quando il tema lo carica correttamente.

Prima di mandare traffico, fai sempre un test reale dal carrello sul tema live. ScriptTag è il percorso legacy Shopify: temi moderni, custom o headless possono richiedere supporto o un app embed dedicato se non caricano lo script.

Per il percorso click-per-click aggiornato usa la guida completa: Connettere Shopify con Dev Dashboard + OAuth.

Requisiti

  • Store Shopify attivo (qualsiasi piano)
  • Permessi di Admin sullo store
  • Account WooshPayment (vedi Quickstart)

1. Avvia l'integrazione

Ci sono due entry point:

A) Dall'onboarding — al primo accesso, step "Piattaforma" → scegli Shopify → crea la dev-app seguendo le istruzioni → incolla dominio, Client ID e Client Secret → "Connetti store".

B) Da Impostazioni — Dashboard → Impostazioni → Connessione Shopify → incolla dominio, Client ID e Client Secret → "Apri autorizzazione Shopify".

Backend internals (per chi vuole capire):

  1. Il form fa POST /api/merchant/shopify/connect-dev con dominio Shopify, Client ID e Client Secret
  2. Salviamo le credenziali cifrate e riceviamo l'URL OAuth Shopify
  3. Ti redirigiamo su Shopify, dove autorizzi l'app nel tuo admin
  4. Shopify ci rimanda al callback, scambiamo il code per accessToken
  5. Cifriamo l'accessToken (AES-256-GCM) e lo salviamo associato al tuo merchant
  6. Installiamo lo ScriptTag e lo stato checkout viene verificato
  7. Ti rimandiamo in dashboard con shopifyConnected: true: significa OAuth autorizzato, non traffico certificato. Prima del traffico servono ancora piano attivo, Whop/COD pronto e test reale dal carrello live.

2. Scope OAuth richiesti

ScopeA cosa serve
read_productsLeggere titoli, prezzi, varianti, immagini per il checkout
read_orders / write_ordersCreare l'ordine sul tuo Shopify dopo pagamento confermato
read_checkouts / write_checkoutsGestire la sessione checkout
read_customersAuto-fill indirizzo per clienti già registrati
read_script_tags / write_script_tagsInstallare/aggiornare il ScriptTag di redirect

Nessun permesso write_products o write_customers. WooshPayment legge il tuo catalogo e i tuoi clienti ma non li modifica mai.

3. Lo ScriptTag

Installato automaticamente al callback OAuth. Quando un cliente clicca "Checkout" dal carrello Shopify:

  1. Lo script intercetta il click prima della redirect nativa
  2. Cattura il carrello (line items + totale + currency)
  3. Chiama POST /api/checkout/create (WooshPayment)
  4. Redirige a https://{tuo-slug}.wooshpayment.com/checkout/{token} (o checkout.tuodominio.com se hai mappato un dominio custom)

Nel percorso standard non devi incollare codice nel tema. Il test decisivo però è sempre dal carrello reale sul tema pubblicato: se il click resta sul checkout Shopify, non lanciare traffico e usa Script tag debug o il supporto per una validazione app embed/custom. Quando disinstalli l'app da Shopify, lo ScriptTag viene rimosso automaticamente.

4. Verifica che funzioni

Questa verifica è obbligatoria anche se la dashboard mostra lo ScriptTag come presente.

  1. Apri il tuo store in finestra in incognito (per saltare cache + cookie)
  2. Aggiungi un prodotto al carrello
  3. Clicca "Check out"
  4. Devi atterrare su {tuo-slug}.wooshpayment.com/checkout/...; se resti sul checkout Shopify, il tema live non è pronto per il traffico
  5. Completa un ordine pilota pagato con importo minimo reale o sandbox Whop esplicitamente abilitata dal supporto
  6. Verifica che l'ordine appaia anche in Shopify Admin → Ordini con tag WooshPayment e financial_status: paid

5. Cosa succede dopo il pagamento

  1. Whop manda webhook invoice_paid o membership_activated a https://api.wooshpayment.com/webhooks/whop/payment-update (firmato HMAC-SHA256)
  2. WooshPayment marca la sessione COMPLETED
  3. Chiamiamo la Orders API di Shopify per creare l'ordine reale con financial_status: paid
  4. Shopify decrementa l'inventario e parte il flusso fulfillment standard
  5. Email "ordine confermato" al cliente la manda WooshPayment, brandizzata col nome dello store e con receipt Shopify disattivata per evitare doppioni
  6. WooshPayment manda al merchant una notifica via Resend (noreply@wooshpayment.com)

Errori comuni

Subito dopo OAuth la dashboard dice "Non connesso"

Bug noto di stale localStorage. Soluzione: refresh della pagina con Cmd+Shift+R. La store fa refreshMerchant() al mount e recupera lo stato corretto.

ScriptTag non sembra installato

Vai in Shopify Admin → App → WooshPayment. Se l'app c'è ma il bottone Checkout non redirige:

  1. Hard refresh dello store (Cmd+Shift+R) per pulire la cache JS
  2. Se persiste: disinstalla l'app da Shopify, torna in WooshPayment e ri-avvia l'OAuth dalle Impostazioni
  3. Se ancora niente: Script tag debug

Ordini non creati in Shopify

L'ordine compare in WooshPayment ma non su Shopify:

  • Verifica in Dashboard → Ordini lo stato della sessione. Se è COMPLETED ma manca l'Ordine store, il problema è la chiamata Orders API
  • Controlla che lo scope write_orders sia ancora attivo: a volte una disinstallazione/reinstallazione parziale lascia scope vecchi
  • Soluzione veloce: disconnetti e ri-autorizza da Impostazioni

"Carrello non valido" lato cliente

Probabilmente i prezzi del prodotto sono cambiati tra add-to-cart e checkout. Il cliente refresha il carrello.

Disinstallare

  1. Shopify Admin → App → WooshPayment → Disinstalla — revoca permessi, ScriptTag rimosso
  2. In WooshPayment lo stato Shopify diventa "Non connesso"; il merchant resta ma senza poter creare ordini sul tuo store

Prossimi step