WWooshPayment docs
Integrazione store

Integrazione Shopify

Connetti Shopify a WooshPayment via OAuth Public App. ScriptTag auto-installato, ordini sincronizzati, scope minimi.

3 min di lettura

L'integrazione Shopify usa OAuth Public App per leggere il catalogo, creare gli ordini, e installare uno ScriptTag che intercetta il bottone "Checkout" e lo redirige sul tuo checkout WooshPayment.

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 → form domain → "Connetti".

B) Da Impostazioni — Dashboard → Impostazioni → Connessione Shopify → inserisci il tuo tuo-store.myshopify.com → "Avvia OAuth".

Backend internals (per chi vuole capire):

  1. Il form fa POST /api/auth/shopify/install con shopDomain + un handoff token JWT (la tua sessione attuale)
  2. Riceviamo URL OAuth Shopify e ti redirigiamo lì
  3. Tu autorizzi sull'admin del tuo store
  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 in automatico
  7. Ti rimandiamo in dashboard con shopifyConnected: true

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)

Niente copia/incolla nel tema, niente modifica a theme.liquid. Quando disinstalli l'app da Shopify, lo ScriptTag viene rimosso automaticamente.

4. Verifica che funzioni

  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/...
  5. Completa un ordine pilota con carta di test Whop 4242 4242 4242 4242
  6. Verifica che l'ordine appaia anche in Shopify Admin → Ordini con tag WooshPayment e payment_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 payment_status: paid
  4. Shopify decrementa l'inventario e parte il flusso fulfillment standard
  5. Email "ordine confermato" al cliente la manda Shopify, non noi
  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 shopifyOrderId è vuoto, 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