WWooshPayment docs
Pagamenti

Collegare Whop a WooshPayment (fast-track)

Guida visiva passo-passo per collegare il tuo account Whop a WooshPayment. Crea una chiave API dedicata, rivelala e incollala in Dashboard → Integrazioni. 5 minuti.

8 min di lettura

Collegare Whop a WooshPayment — guida visiva 2026

Whop è il processor che WooshPayment usa per accettare carte, Apple Pay e Google Pay sul tuo checkout brandizzato. Per collegarlo basta una chiave API generata dalla Dev Dashboard di Whop e incollata in WooshPayment.

Tempo necessario: 5 minuti. Niente Apple Developer Account, niente verifica documenti finché non superi i $500/mese di payout.

Cosa ti serve alla fine di questa guida: una chiave API apik_xxx… generata sulla tua Company Whop e incollata in Dashboard → Integrazioni → Whop.

Prerequisiti

  • Account Whop Business con almeno una Company creata (se non ce l'hai: whop.com/signup)
  • Permessi Amministratore sulla Company (Owner anche meglio)
  • Un Product di tipo One-time payment già creato sulla Company — vedi Setup Whop completo se ti serve crearlo

In WooshPayment ti basta aver completato lo step "Piattaforma" dell'onboarding (Shopify o WooCommerce connesso).

1. Apri la Whop Dashboard sulla Company giusta

Whop Dashboard Home della Company "Elvyora" con sidebar sinistra che include Home (attivo), Pagamenti, Utenti, Saldature, Carte, Annunci con badge "Nuovo", Chat di supporto, sezione "In evidenza" con Prodotti, e in basso "Sviluppatore" evidenziato in viola con callout "click QUI". Main area mostra "Today" con loading spinner e card Saldo totale -65,18 € + Payouts 240,88 € Completato. Sidebar destra apre AI chat "Nuova chat" con suggerimenti.

  1. Vai su whop.com/dashboard
  2. In alto a sinistra, seleziona la Company giusta dal dropdown (es. Elvyora)
  3. Atterri sul Cruscotto (Home)
  4. Nella sidebar in basso, clicca Sviluppatore (icona </>)

La sidebar di Whop è la stessa per tutte le Company. Se vedi più Company, occhio a essere su quella corretta — la chiave API che generi è scoped alla Company selezionata.

2. Apri "Company API keys" e clicca "+ Crea"

Whop Sviluppatore con tab "Company API keys" attiva. Tabella mostra 3 chiavi esistenti: WooshStore (apik_q62u••••b951, 6 giorni fa), Test Launch Store (apik_Cifd••••b851, 10 giorni fa), LASSO (apik_hWws••••d57a, 5 mesi fa). Sopra la tabella, sub-text "Le chiavi API permettono ai sistemi esterni di parlare con Whop a tuo nome" e bottone blu "+ Crea" in alto a destra evidenziato con callout "click QUI". Sotto la tabella: sezione "Apps" + bottone "+ Create app".

  1. La tab Company API keys è già attiva
  2. Vedrai eventuali chiavi esistenti (se è la prima volta, lista vuota)
  3. In alto a destra, clicca + Crea

Crea sempre una chiave dedicata a WooshPayment, anche se hai già altre chiavi. Etichettare ogni chiave per il servizio che la usa rende molto più facile ruotare o revocare senza rompere altre integrazioni.

3. Compila il modal "Crea chiave API"

Modal "Crea chiave API" di Whop sopra dashboard sfocato. Campo Nome con placeholder "Inserisci il nome della chiave API" evidenziato in viola e callout "scrivi qui". Sotto: dropdown "Eredita permessi dal ruolo" settato su "Amministratore". Search box "Cerca permessi" sotto. Lista permessi expandible con Member 0/2, Membership 0/2, Payment 0/1, Webhook Receive 0/1. Link blu "Mostra 42 categorie in più". Footer: bottoni "Annulla" e "Crea" blu primary.

  1. Nome: digita qualcosa di riconoscibile, es. WooshPayment o il-mio-store
    • È solo un'etichetta interna sulla tua Company Whop — i tuoi clienti non la vedono mai
  2. Eredita permessi dal ruolo: lascia su Amministratore (default)
    • Il ruolo Amministratore copre tutto ciò che serve a WooshPayment per processare pagamenti e leggere ordini
  3. NON spuntare singoli permessi nella lista — la chiave eredita già tutto dal ruolo
  4. Clicca Crea in basso a destra

Se WooshPayment ti risponde 401 — does not have permission to access this route dopo il connect, la chiave è stata generata con un ruolo troppo basso. Torna qui, cancella la chiave, e ricreala con ruolo Amministratore o Proprietario.

4. La chiave è creata — clicca l'occhio per rivelarla

Modal "Dettagli della chiave API" con box che mostra la chiave mascherata "apik_JwX9••••bcc3" e 4 icone a destra: Ruota (arancio), Occhio (evidenziato in viola con callout "click occhio per rivelare"), Copia, Cestino rosso. Bottone "Edit permissions" blu sotto. Footer "Chiudi". Toast notification verde in fondo "✓ Chiave API creata con successo".

Whop apre il modal Dettagli della chiave API. La chiave è mostrata mascherata (es. apik_JwX9••••bcc3) — è una misura di sicurezza, ma per noi non serve così.

  1. Clicca l'icona occhio 👁 per rivelare la chiave intera

5. Copia la chiave intera

Modal "Dettagli della chiave API" con warning arancio "Questa chiave è mostrata SOLO UNA VOLTA. Copiala adesso." Box giallo evidenziato con chiave completa "apik_JwX9vv89apgDP_C3908756_C_8674024ea6e7cc973decb939a862edf4c27f3daabca74b19a7bda966e2bcc3" su multi-line wrap. A destra colonna di icone (Ruota, Occhio, Copia evidenziata con callout "click COPY", Cestino).

Adesso la chiave è visibile in chiaro (apik_JwX9vv89apgDP_…). Clicca l'icona Copia 📋 a destra.

La chiave è mostrata UNA SOLA VOLTA. Se chiudi il modal senza copiare, dovrai cancellarla e crearne una nuova (vecchia chiave non più rivelabile). Per sicurezza, dopo averla incollata in WooshPayment, NON salvarla altrove — è già cifrata AES-256-GCM nel nostro DB.

6. Incolla in WooshPayment → Integrazioni

WooshPayment Dashboard sezione Integrazioni in stato post-connect. Sidebar sinistra dark navy con logo "W WooshPayment" + tag "Beta", sotto "Alba Moretti / 1hcfze-ut.myshopify.com" + tag "Starter", nav con Integrazioni evidenziato. Top banner viola "Manca poco al lancio del tuo checkout — 5/5 completati" con checkmarks verdi su Store/Subdomain/Brand/Spedizioni/Whop Payments. Main: titolo "Integrazioni" + bottone "Guida". Sezione "Integrazione principale" con card Whop bordata in verde: logo viola "W" + nome "Whop" + badge verde "Connesso" + sub "Collega il tuo account Whop..." + "Business ID: biz_eKNqey9jlu9Qe0" + bottone rosso "Disconnetti". Banner verde sotto "Account Whop collegato!". Callout viola "così deve apparire post connect". Sezione "Piattaforma store" con card WooCommerce "Non connesso".

Adesso torna su WooshPayment:

  1. Vai su Dashboard → Integrazioni (wooshpayment.com/dashboard/integrations)
  2. Trova la card Whop nella sezione "Integrazione principale"
  3. Incolla la chiave (apik_…) nell'input API Key
  4. Compila anche il Product ID se richiesto (vedi setup Whop completo per recuperare il prod_xxx dall'URL del prodotto)
  5. Clicca Connetti Whop

Risposta in ~1 secondo:

  • ✅ Verde "Account Whop collegato!" + badge ✓ Connesso + Business ID visibile (es. biz_eKNqey9jlu9Qe0)
  • ❌ Rosso: vedi Troubleshooting

Cosa fa il backend dietro le quinte

  • Testa la chiave contro https://api.whop.com/v5/company (timeout 6s)
  • Recupera il businessId (biz_xxx) e lo memorizza nel DB
  • Salva tutto cifrato AES-256-GCM (whopApiKey, whopBusinessId, whopConnected=true)
  • Fire-and-forget: registra il dominio del tuo checkout come Apple Pay domain sul tuo Whop (vedi Apple Pay)

Troubleshooting

401 — does not have permission to access this route

La chiave è stata generata con un ruolo troppo basso. Torna su step 3, elimina la chiave attuale, e creane una nuova con ruolo Amministratore (o Proprietario).

Chiave API invalida

  • La chiave è stata copiata male — verifica che non ci siano spazi davanti/dietro
  • La chiave inizia con apik_ (non whk_ che è il webhook secret)
  • La Company che ha generato la chiave è ancora attiva (Whop non l'ha sospesa)

Product ID non valido

Hai messo un prod_xxx di un'altra Company. Il biz_xxx dell'URL del prodotto deve coincidere col Business ID visibile in WooshPayment dopo il connect.

Il prezzo del prodotto sostituisce il totale del carrello

Il prodotto Whop è stato salvato con un piano ricorrente fisso invece di One-time payment. WooshPayment non può sovrascrivere il prezzo se il prodotto ha un piano fisso. Soluzione: torna sul prodotto Whop → Modifica → cambia il tipo a Una tantum → Salva. Non serve riconnettere su WooshPayment.

Ho rigenerato la chiave e ora non funziona più

La vecchia chiave smette di funzionare al momento della rigenerazione. Vai su Dashboard → Integrazioni → Whop → Disconnetti → incolla la nuova chiave → Connetti Whop.

⚠️ Passaggio OBBLIGATORIO: la chiave di firma del webhook (ws_)

Senza questo passaggio, i clienti pagano ma gli ordini non compaiono su Shopify (e nemmeno nella tua dashboard). È il problema #1 da evitare.

Perché serve: quando un cliente paga, Whop manda a WooshPayment una notifica firmata con un segreto del tuo account. WooshPayment verifica quella firma prima di creare l'ordine. Se non ci dai il segreto, la notifica viene rifiutata e l'ordine non viene creato in tempo reale.

Come prenderla (1 minuto):

  1. Vai su Whop → Developer → Webhooks: dash.whop.com/settings/developer/webhooks
  2. Trova (o crea) l'endpoint che punta a https://api.wooshpayment.com/webhooks/whop/payment-update
  3. Negli eventi assicurati che siano attivi almeno payment.succeeded e membership.went_valid (o membership.activated)
  4. Copia il Signing secret — inizia con ws_
  5. Incollalo in WooshPayment → Dashboard → Integrazioni → Whop, nel campo Chiave di firma webhook, e salva

Fatto: da quel momento i tuoi ordini compaiono all'istante su Shopify.

Già collegato prima di questo aggiornamento? Trovi un riquadro giallo "Aggiungi la chiave webhook" in Dashboard → Integrazioni → Whop. Nel frattempo WooshPayment recupera comunque gli ordini in automatico ogni paio di minuti, ma con la chiave diventano istantanei.

FAQ

Posso usare la stessa chiave per più store?

Tecnicamente sì, ma sconsigliato. Crea una chiave separata per ogni store WooshPayment — così se vuoi disconnettere uno store puoi revocare solo la sua chiave senza toccare gli altri.

La chiave scade?

No, non scade. Resta valida finché:

  • Non la elimini tu manualmente da Whop → Sviluppatore
  • Non rimuovi il ruolo dall'utente che l'ha creata
  • Whop non sospende il tuo account per violazione TOS

Cosa cambia tra Amministratore e Proprietario?

Per WooshPayment entrambi vanno bene. La differenza la senti quando vuoi cambiare impostazioni di fatturazione, payout o membri della Company — quelle restano per il Proprietario. Per processare pagamenti, l'Amministratore basta.

Prossimi step