Stripe

Dove nell'amministrazione: Finance › Payment channels › Stripe (/payments/stripe). Interruttori e commissioni: Finance › Payment channels › Fees & limits (/payments/fees).

Descrizione

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. Usalo come canale principale per i clienti internazionali.

Requisiti

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.

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

Sul lato Stripe:

1. Accedi alla Stripe Dashboard. 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.

Collega 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://<your-domain>/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.

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://<your-domain>/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

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.

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 è 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

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

• 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.
• 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://<their-domain>/v1/billing/stripe/webhook/r/<id>); vedi Resellers.

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.