--- title: Stripe description: Collega Stripe a NexCMP per pagamenti con carta, Apple Pay, Google Pay, Link e Alipay: chiavi API, webhook, registrazione dominio e pagamento di test. url: https://nexcmp.com/it/docs/billing/stripe/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # Stripe > **Dove nell'amministrazione:** Finance › Payment channels › Stripe (`/payments/stripe`). Interruttori e commissioni: Finance › Payment channels › Fees & limits (`/payments/fees`). ## Descrizione {#what-it-does} Stripe accetta pagamenti con carta per le ricariche del credito. Con lo stesso account puoi anche offrire **Apple Pay**, **Google Pay**, **Link** e **Alipay**, e consentire ai clienti di **salvare una carta** per la [ricarica automatica](https://nexcmp.com/it/docs/billing/auto-top-up/). Usalo come canale principale per i clienti internazionali. ## Requisiti {#requirements} | Elemento | Requisito | |---|---| | Account Stripe | Un account Stripe in grado di accettare pagamenti in **USD**. Alipay viene addebitato in JPY e deve essere attivato da Stripe per il tuo account. | | Chiavi | Una chiave segreta (`sk_live_...` o `sk_test_...`) e una chiave pubblicabile (`pk_live_...` o `pk_test_...`). Il modulo accetta solo chiavi con questi prefissi. | | Rete | Il tuo pannello deve essere raggiungibile via HTTPS da Internet (Stripe chiama il webhook) e deve raggiungere `api.stripe.com` sulla porta 443. | | Dominio (solo crediti) | Il dominio utilizzato dai clienti deve servire `/.well-known/apple-developer-merchantid-domain-association` — NexCMP lo fa per te. | | Dipendenze | Nessuno. | ::: info Account Stripe condivisi NexCMP elabora solo gli eventi webhook per i pagamenti creati autonomamente, quindi puoi utilizzare un account Stripe che serve anche un'altra applicazione. ::: ## Prepara l'infrastruttura {#prepare-the-infrastructure} Sul lato Stripe: 1. Accedi alla [Stripe Dashboard](https://dashboard.stripe.com). Attiva o disattiva **Test mode** per decidere se stai effettuando una prova o l'attivazione in produzione. Le chiavi di una modalità non funzionano mai con l'altra. 2. Apri **Developers › API keys**. Copia la **Publishable key**, quindi rivela e copia la **Secret key**. Mantieni segreta la chiave segreta. 3. (Facoltativo) Apri **Settings › Payment methods** e attiva **Alipay** se desideri offrirlo. 4. Non **devi** creare il webhook manualmente — NexCMP può crearne uno per te (vedi il passaggio 5 di seguito). Se preferisci farlo manualmente, crea un endpoint in **Developers › Webhooks** con l'URL e gli eventi elencati in [Webhook](#webhook). ## Collega in NexCMP {#connect-in-nexcmp} 1. Apri **Finance › Payment channels › Stripe** (`/payments/stripe`). 2. Nella scheda **API keys** scegli **Mode** (`live` o `test`), incolla la **Secret key** e la **Publishable key**. 3. Fai clic su **Save**. Le chiavi vengono scritte in un file di configurazione sul server che solo l'account di servizio NexCMP può leggere. Non vengono mai reinviate al browser; successivamente la pagina mostra solo gli ultimi 4 caratteri. 4. Fai clic su **Check**. Una finestra di dialogo riporta la connessione, la modalità, il saldo disponibile e in sospeso, l'ID account, se gli addebiti sono abilitati, se esiste un webhook e se Alipay è disponibile. Una linea rossa indica che quella parte richiede attenzione. 5. Nella scheda **Webhook** fai clic su **Create webhook** e conferma. NexCMP chiede a Stripe di creare l'endpoint con tutti gli eventi richiesti e compila automaticamente **Webhook signing secret** (`whsec_...`). L'URL precompilato nel campo è `https:///v1/billing/stripe/webhook`, ad esempio `https://cloud.example.com/v1/billing/stripe/webhook`. 6. Apri **Fees & limits** (`/payments/fees`), tieni attivo **Card (Stripe)**, imposta **Stripe fee %** e **Stripe fixed fee (cents)** sulla tua tariffa reale e fai clic su **Save channels & fees**. Vedi [Payment channels](https://nexcmp.com/it/docs/billing/payment-channels/#switches-and-fees-fees-limits). ![Pagina di Stripe con modalità, chiave segreta e chiave pubblicabile compilate con valori di esempio](https://nexcmp.com/it/docs/images/billing/stripe-01-keys.webp) ### Webhook {#webhook} Il banner rosso "Missing webhook_secret" rimane visibile finché non viene salvato un segreto di firma. Senza di esso, le ricariche con Stripe **non vengono registrate**, anche se Stripe ha incassato i fondi. | Elemento | Valore | |---|---| | URL | `https:///v1/billing/stripe/webhook` | | Events | `checkout.session.completed`, `payment_intent.succeeded`, `payment_intent.payment_failed`, `charge.refunded`, `charge.dispute.created`, `charge.dispute.closed`, `radar.early_fraud_warning.created`, `refund.updated`, `refund.failed` | | Signature | Stripe `Stripe-Signature` header, HMAC-SHA256, tolleranza di 300 secondi. Le richieste con una firma non valida ricevono HTTP 400. | | Idempotency | Ogni ID evento viene memorizzato una sola volta; una consegna ripetuta non accredita mai due volte. | Se hai eseguito l'aggiornamento da una versione che registrava un numero inferiore di eventi, fai di nuovo clic su **Create webhook**: il vecchio endpoint viene mantenuto, quindi eliminalo manualmente in seguito nella Dashboard di Stripe. Le righe **24h events** e **Latest event** nella scheda Webhook indicano se Stripe sta raggiungendo il pannello. I singoli eventi sono elencati in **Payment channels › Gateway events** (`/payments/events`, scheda Stripe), dove ciascun evento può essere visualizzato (**Payload**) o rigiocato (**Replay**). ### Apple Pay, Google Pay e Link {#apple-pay-google-pay-and-link} 1. Nella scheda **Wallets (Apple Pay · Google Pay · Link) & Alipay**, il campo **Customer app Domain registered with Stripe** è precompilato con il nome host del tuo sito (ad esempio `cloud.example.com`). 2. Fai clic su **Register / verify domain** e conferma. NexCMP registra il dominio nei domini dei metodi di pagamento di Stripe e chiede a Stripe di validarlo. 3. Il risultato mostra lo stato di **Apple Pay**, **Google Pay** e **Link**. Apple Pay viene visualizzato solo quando lo stato è `active`. 4. In **Fees & limits** tieni **Apple Pay · Google Pay · Link** attivo. ![Scheda del portafoglio che mostra il dominio registrato e gli stati di Apple Pay, Google Pay e Link](https://nexcmp.com/it/docs/images/billing/stripe-03-wallets.webp) ::: tip Apple Pay rimane inattivo Apple Pay richiede che il file di associazione del dominio risponda con HTTP 200 sul tuo dominio pubblico. Se metti Cloudflare o un altro proxy davanti, non bloccare `/.well-known/`. ::: ### Alipay {#alipay} Alipay è facoltativo. Attivalo in **Stripe Dashboard › Settings › Payment methods**, fai clic su **Check** e attendi che la finestra di dialogo mostri che Alipay è disponibile, quindi attiva **Alipay (Stripe, JPY display)** in **Fees & limits**. Imposta **Alipay fee %**, **Alipay fixed fee**, il **tasso ¥/USD** (50–500) e lo **spread FX %** (0–20). Aggiorna regolarmente il tasso ¥/USD; la pagina avvisa quando è più vecchio di 7 giorni. ## Verifica {#verify} 1. In modalità di test, accedi al portale come cliente di test, apri **Billing**, fai clic su **Deposit**, scegli **Card** e paga l'importo minimo con la carta di test Stripe `4242 4242 4242 4242` (qualsiasi data futura, qualsiasi CVC). 2. Il saldo aumenta nel giro di pochi secondi e il pagamento compare in **Finance › Billing › Top-ups** con lo stato *Completed*. 3. Apri **Payment channels › Gateway events › Stripe**: dovresti vedere `checkout.session.completed` o `payment_intent.succeeded` con un'ora di elaborazione. 4. Tornando alla pagina di Stripe, **24h events** è superiore a 0. Prima di passare alla produzione, imposta **Mode** su `live`, incolla le chiavi live e fai di nuovo clic su **Create webhook** (i webhook della modalità di test e di produzione sono separati). ## Limiti e note {#limits-notes} - **Importi e valuta.** I portafogli sono in USD. I pagamenti con carta, portafoglio e link vengono addebitati in USD; Alipay viene mostrato al cliente in JPY e convertito al tuo tasso. - **Commissioni.** La commissione effettiva di Stripe non viene letta automaticamente indietro; la percentuale di commissione impostata determina ciò che vede il cliente e ciò che viene accreditato sul portafoglio. Scegli **Customer pays top-up fee** in *Fees & limits* per addebitare la commissione in aggiunta. - **Carte salvate.** Quando il cliente seleziona *Save card for auto top-up*, la carta viene memorizzata su Stripe, non sul tuo server. Vedi [Saved payment methods](https://nexcmp.com/it/docs/billing/saved-payment-methods/). - **Rimborsi.** Il rimborso sulla carta è un processo in due fasi: un amministratore crea una richiesta di rimborso per un pagamento completato (**Finance › Billing › Top-ups**, azione di rimborso sul pagamento) e poi l'approva in **Finance › Payouts › Card refunds** (`/billing/payouts`). I rimborsi Alipay sono asincroni; uno non riuscito (`refund.failed`) restituisce l'importo trattenuto al portafoglio. - **Contestazioni.** Su `charge.dispute.created` NexCMP blocca l'account del cliente, interrompe i suoi servizi prepagati (nulla viene eliminato) e invia un avviso all'amministratore. Se vinci (`charge.dispute.closed`), l'importo viene riaccreditato sul portafoglio. - **Pagamenti in attesa.** Se un webhook non arriva mai, NexCMP verifica autonomamente i pagamenti rimasti in sospeso per più di 10 minuti rispetto a Stripe e li completa. I pagamenti più vecchi di 7 giorni vengono ignorati. - I **Resellers** possono collegare il proprio account Stripe (webhook `https:///v1/billing/stripe/webhook/r/`); vedi [Resellers](https://nexcmp.com/it/docs/customers/resellers/). ## Troubleshooting {#troubleshooting} | Sintomo | Causa | Soluzione | |---|---|---| | "La chiave segreta deve iniziare con sk_live_/sk_test_" | Chiave errata incollata | Incolla la chiave segreta da **Developers › API keys**. | | "La chiave segreta non corrisponde alla modalità live/test" | Modo e chiave non corrispondono | Fai in modo che il **Mode** corrisponda al prefisso della chiave. | | "La chiave pubblicabile deve iniziare con pk_" | Chiave errata | Usa la chiave pubblicabile. | | Il controllo indica che la connessione non è riuscita | Chiave errata, chiave revocata oppure il server non riesce a raggiungere `api.stripe.com` | Incolla nuovamente la chiave; esegui un test con `curl -I https://api.stripe.com` dal server. | | Banner rosso "Missing webhook_secret" | Il segreto di firma non è salvato | Fai clic su **Create webhook** oppure incolla il `whsec_...` secret dalla Dashboard di Stripe e fai clic su **Save**. | | Denaro prelevato ma il saldo non è cambiato | Webhook non consegnato o firma non valida | Verifica che l'URL termini con `/v1/billing/stripe/webhook`, che il segreto corrisponda all'endpoint e riproduci l'evento in **Gateway events**. In Stripe, apri l'endpoint e controlla i tentativi di consegna (HTTP 400 indica un segreto di firma errato). | | Il fallimento di "Create webhook" | L'URL non è HTTPS o non è raggiungibile | Usa il tuo dominio `https://` pubblico. | | Stato Apple Pay non attivo | Dominio non convalidato | Fai di nuovo clic su **Register / verify domain** dopo che il file di associazione del dominio risponde con 200. | | Alipay non disponibile nella finestra di dialogo di controllo | Non attivato su Stripe | Attivalo nella Dashboard di Stripe, quindi fai clic su **Check**. | | Il cliente non vede alcun modulo per le carte | **Card (Stripe)** è disattivato o manca la chiave segreta | Attivalo in **Fees & limits** e salva le chiavi. |