WWooshPayment docs
Pagamenti

Collegare Whop a WooshPayment

Guida visiva passo-passo per collegare Whop a WooshPayment con API key, Product ID e webhook signing secret, poi verificare il percorso pagamento prima del traffico.

8 min di lettura

Collegare Whop a WooshPayment — guida visiva 2026

Whop è il processor che WooshPayment usa per accettare carte e wallet idonei sul tuo checkout brandizzato. I wallet appaiono solo quando account Whop, dominio checkout, browser e device li supportano. Per rendere i pagamenti davvero pronti servono API key, Product ID e webhook signing secret.

Questo è un setup guidato, non una certificazione per mandare traffico. Whop puo' richiedere verifiche aggiuntive in base ad account, volume payout e risk review, e WooshPayment è pronto al traffico solo dopo un ordine pilota pagato che prova webhook, ordine store, email, pixel/CAPI e return page.

Cosa ti serve alla fine di questa guida:

  1. API key apik_xxx... generata sulla tua Company Whop
  2. Product ID prod_xxx... di un prodotto Whop one-time
  3. Webhook signing secret ws_xxx... dell'endpoint Whop verso WooshPayment

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

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 il Product ID (vedi setup Whop completo per recuperare il prod_xxx dall'URL del prodotto)
  5. Verifica che sia presente anche il webhook secret: serve per validare gli eventi pagamento e creare gli ordini sullo store senza ritardi
  6. Clicca Connetti Whop

Risposta in ~1 secondo:

  • ✅ Stato verde quando Whop è pronto: API key valida, Business ID letto, Product ID salvato e webhook secret presente
  • ⚠️ Stato amber se la API key è valida ma mancano Product ID o webhook secret: completa la card prima del traffico
  • ❌ 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
  • Valida che il Product ID appartenga alla stessa Company
  • Salva tutto cifrato AES-256-GCM (whopApiKey, whopBusinessId, whopAccessPassId, eventuale whopWebhookSecret, whopConnected=true)
  • Per i wallet idonei puo' partire un tentativo best-effort di registrazione dominio Apple Pay, ma considera la disponibilità wallet pronta solo dopo aver verificato dominio e comportamento wallet nel tuo Whop dashboard/device seguendo 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. 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 gli eventi Whop possono creare ordini store appena Whop conferma il pagamento e il webhook viene accettato.

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 periodicamente, ma la chiave webhook è richiesta per il percorso primario di creazione ordine in tempo reale.

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