Connetti Whop a WooshPayment — guida visiva 2026

Whop è il processore di pagamento che WooshPayment usa per accettare carte e, quando account/dominio/device sono compatibili, wallet come Apple Pay e Google Pay. Il collegamento tecnico richiede tutti i passaggi sotto: API key, Product ID, webhook signing secret e test reale prima del traffico.

Perché serve un Product ID

WooshPayment crea ogni checkout come una "vendita" del tuo prodotto Whop. Per questo serve un prodotto Whop dedicato dove far cascare tutte le vendite del tuo store. Il prodotto deve essere:

• Una tantum (one-time payment), non ricorrente
• Senza piani fissi: il prezzo lo decidiamo noi a runtime dal carrello del cliente

Senza Product ID, l'iframe Whop nel checkout non sa dove creare l'invoice e si blocca con errore.

Prerequisiti

• Account Whop Business (non Personal) con una Company già creata
• Permessi Amministratore sulla Company (Proprietario va benissimo)
• Email verificata + dati legali base compilati (richiesti per payout > $500/mese)

Se non hai ancora l'account: crealo qui, poi torna su questa guida.

1. Apri la sezione Prodotti sul tuo Whop

1. Vai su whop.com/dashboard e seleziona la Company giusta in alto a sinistra
2. Sidebar → Prodotti (sezione "In evidenza")

Vedrai la tua lista prodotti (vuota se è il primo). In alto a destra c'è il bottone + Crea prodotto.

2. Click "+ Crea prodotto" e compila i dettagli

1. Click sul bottone + Crea prodotto in alto a destra
2. Si apre la pagina Aggiungi prodotto con:
   • Nome (obbligatorio): scrivi qualcosa come WooshPayment Checkout — questo è il nome interno, i tuoi clienti non lo vedono
   • Titolo (opzionale): puoi lasciarlo vuoto
3. Sezione Prezzi sotto: di default è selezionato "Accesso gratuito" ← lo cambiamo al prossimo step

3. Click "Accesso a pagamento"

Nella sezione Prezzi, click sulla card Accesso a pagamento (la seconda, con l'icona del dollaro).

Whop ti mostra subito una card di prezzo con valori default: 29,99 USD / mese, tipo Ricorrente.

4. Cambia il tipo da "Ricorrente" a "Una tantum"

1. Click sul dropdown Ricorrente (sotto il prezzo)
2. Seleziona Una tantum (one-time payment)
3. Verifica che il preview a destra ora mostri il bottone "Acquista ora" (non più "Unisciti ora") — è il segnale che il tipo è cambiato correttamente
4. Il prezzo di default 29,99 USD non importa, WooshPayment lo sovrascrive col totale reale del cliente — lasciaci pure quello
5. Lascia gli altri toggle disattivati: niente "Includi una prova gratuita", niente "Accetta pagamenti in valuta locale"

In alto a destra click Avanti per arrivare allo step App (puoi saltarlo: WooshPayment non usa app Whop) → Avanti di nuovo → step Pagina (puoi saltarlo) → infine Salva prodotto in alto a destra.

5. Copia il Product ID (prod_xxx) dall'URL

Dopo il salvataggio Whop ti porta sulla pagina del prodotto appena creato. Guarda la barra dell'indirizzo del browser: contiene l'ID del prodotto in formato prod_xxxxxxxxxxxxx.

Esempio URL:

https://whop.com/dashboard/biz_eKNqey9jlu9Qe0/products/prod_79AacrnFwMXjs/
                                                       ^^^^^^^^^^^^^^^^^^
                                                       questo è il tuo Product ID

Copialo — ti serve dopo in WooshPayment.

6. Genera la API Key

1. Sidebar Whop → Sviluppatore (in basso, sopra Impostazioni)
2. Atterri sulla pagina Company API keys
3. Vedi la lista delle key esistenti (se è la prima volta è vuota) + bottone + Crea in alto a destra

7. Click "+ Crea" → ruolo "Amministratore"

1. Click sul bottone + Crea della sezione Company API keys
2. Si apre il modal Crea chiave API con:
   • Nome: scrivi qualcosa come WooshPayment (è solo un'etichetta interna per ricordarti dove l'hai usata)
   • Eredita permessi dal ruolo: dropdown default su Amministratore
3. Lascia Amministratore oppure scegli Proprietario se preferisci
4. NON spuntare singoli permessi — eredita tutto dal ruolo
5. Click Crea in basso a destra

8. Copia la API Key

Dopo il click su Crea, Whop ti mostra la key in formato apik_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx. Copiala subito — Whop la mostra solo una volta. Se la perdi, la cancelli e ne crei una nuova.

9. Incolla API key e Product ID in WooshPayment

Adesso torna su WooshPayment Dashboard:

1. Vai su Dashboard → Integrazioni (wooshpayment.com/dashboard/integrations)
2. Scorri fino alla card viola Whop
3. Compila i campi:
   • API Key Whop: incolla apik_... (la key che hai appena copiato)
   • Product ID: incolla prod_... (l'ID dall'URL del prodotto)
   • Webhook signing secret: se lo hai già creato, incolla ws_...; altrimenti completa lo step 10 e salva il secret subito dopo
4. Click Connetti Whop

Risposta in ~1 secondo:

• ✅ La API key viene validata e il Business ID viene salvato
• ⚠️ La card resta da completare finche' non aggiungi anche il webhook signing secret dello step 10
• ❌ Se rosso: vedi la sezione Troubleshooting sotto

Cosa fa il backend dietro le quinte:

• Testa la API key contro https://api.whop.com/v5/company (timeout 6s)
• Testa che prod_xxx esiste e appartiene alla tua Company (api.whop.com/api/v2/products/{prod_xxx})
• Se entrambi 200 → salva tutto cifrato (AES-256-GCM): whopApiKey, whopBusinessId, whopAccessPassId, eventuale whopWebhookSecret, whopConnected=true
• Per Apple Pay puo' partire un tentativo best-effort di registrazione dominio, ma considera Apple Pay pronto solo dopo aver verificato il dominio nel tuo Whop dashboard seguendo Apple Pay

10. Configura il webhook (1 volta, manuale)

Per ricevere notifiche di pagamento il webhook Whop deve puntare a noi:

1. Whop Dashboard → Sviluppatore → scorri fino a Webhooks
2. Click + Crea webhook
3. Endpoint URL: https://api.wooshpayment.com/webhooks/whop/payment-update
4. Eventi da spuntare (minimo richiesto):
   • invoice_paid
   • payment_succeeded
   • membership_activated
   • membership_went_valid
   • payment_failed
   • payment_refunded
5. Salva.
6. Apri il webhook appena creato, copia il Signing secret (ws_...) e incollalo in WooshPayment → Dashboard → Integrazioni → Whop → campo Chiave di firma webhook.
7. Salva il secret in WooshPayment. La card Whop deve diventare verde/pronta.

Se il webhook non è configurato, o se il signing secret non è salvato in WooshPayment, le sessioni possono restare PENDING/in recovery e gli ordini non vengono creati in tempo reale. Il merchant è considerato pronto solo con API key, Product ID e webhook secret presenti.

11. Verifica il money-path

Test rapido end-to-end:

1. Apri il tuo checkout di test su {tuo-slug}.wooshpayment.com/checkout/...
2. Compila email + indirizzo
3. Se sei in produzione, completa un piccolo pagamento reale dal carrello live. Usa carte di test solo se il supporto ha abilitato esplicitamente la sandbox Whop sul tuo merchant.
4. Click Paga
5. Devi vedere il checkout marcato COMPLETED in WooshPayment Dashboard → Ordini
6. Su Whop Dashboard → Pagamenti vedi l'invoice generata col totale corretto
7. Prima del traffico verifica anche ordine store Shopify/Woo, email cliente/merchant, pixel/CAPI e return page

Se sei in sandbox e la carta test viene rifiutata, controlla che l'ambiente sandbox Whop sia davvero attivo sul merchant. Se sei in produzione, una carta test non certifica il money-path: serve un pagamento reale minimo.

Troubleshooting

401 — does not have permission to access this route

La API key è stata generata con un ruolo troppo basso o con permessi custom insufficienti. Torna su step 7, rigenera con ruolo Amministratore o Proprietario, sostituisci la vecchia key in WooshPayment.

Product ID non valido — prod_xxx non trovato

L'ID è di un prodotto di un'altra Company, oppure hai copiato male. Verifica:

• L'URL whop.com/dashboard/biz_xxx/products/prod_xxx/ deve avere biz_xxx uguale al Business ID mostrato in WooshPayment Dashboard
• Niente spazi prima/dopo il prod_
• Il prefisso è prod_, non prd_ o product_

Prezzo addebitato sbagliato (es. $29.99 invece di $50)

Il prodotto Whop è stato salvato con tipo Ricorrente invece di Una tantum. Torna sul prodotto Whop → Modifica → cambia il dropdown a Una tantum → Salva. Non serve riconnettere su WooshPayment.

Whop chiede di verificare la mia identità

Whop blocca i payout > $500/mese se non hai caricato:

• Documento (passaporto o carta d'identità)
• Indirizzo (bolletta o estratto conto)
• Per società: visura camerale

Non mandare traffico contando sui payout finché la verifica richiesta da Whop non è completata o chiarita nel tuo account.

Ho rigenerato la API Key e ora si pianta tutto

La vecchia smette di funzionare immediatamente. Vai su WooshPayment Dashboard → Integrazioni → Whop → Disconnetti → incolla la nuova key + lo stesso prod_xxx → Connetti Whop.

L'iframe Whop si carica vuoto / Apple Pay non appare

Tre possibili cause:

1. Apple Pay: visibile solo su Safari con Wallet card configurata. Su Chrome/Firefox/altro non appare.
2. Domain non verificato: il subdomain del tuo checkout ({slug}.wooshpayment.com o il tuo custom domain) non è registrato come Apple Pay domain sul tuo Whop. Vedi Setup Apple Pay.
3. Webhook mancante: vedi step 10 sopra. Senza webhook le sessioni si bloccano.

Fee dettagliate (Whop)

Le fee Whop sono decise da Whop e possono variare per paese, categoria, profilo di rischio, metodo di payout e conversione valuta. Controlla la tabella fee live nel tuo account Whop prima di mandare traffico.

Le fee WooshPayment dipendono dal tuo piano attivo; le fee Whop restano separate e vanno verificate nel tuo account Whop.

FAQ

Posso usare Stripe invece di Whop?

Non nel prodotto pubblico attuale. WooshPayment usa Whop per carte/wallet; eventuali alternative vengono valutate solo come integrazione custom.

Posso usare un prodotto Whop esistente che ha già piani fissi?

No. WooshPayment richiede un prodotto dedicato con tipo Una tantum senza piani. Crea un nuovo prodotto solo per WooshPayment seguendo questa guida.

Cosa succede se aggiungo un secondo Product al WooshPayment?

Per ora WooshPayment usa un solo Product ID per merchant. Multi-product è in roadmap per merchant con più brand sotto la stessa Company Whop.

La connessione Whop si rinnova da sola? Scade?

L'API Key non scade. Resta valida finché:

• Non la rigeneri tu manualmente
• Non rimuovi il ruolo Company dall'utente che l'ha creata
• Whop non revoca il tuo account (in caso di violazione TOS)

In tutti questi casi, riconnetti seguendo questa guida.

Prossimi step

• Setup Apple Pay — registrare il subdomain del checkout sul tuo Whop
• Refund flow — come gestire i rimborsi
• Webhook spec — payload + sicurezza HMAC