Gateway di pagamento: configurazione completa

Provider e gateway non sono la stessa cosa

Il provider contiene la connessione tecnica a Stripe o TS Pay. Il gateway è il metodo commerciale che compare nelle fatture, nei contratti, nei metodi cliente e, quando consentito, nell’Area Clienti.

L’ordine corretto è: attivare e collaudare il provider, configurare i gateway collegati, rendere disponibili soltanto quelli desiderati, predisporre webhook e infine associare metodi ai clienti. Disattivare il provider nasconde o blocca anche i suoi gateway dipendenti.

Campi comuni di ogni gateway

Stato abilita il metodo; codice e nome interno servono all’amministrazione; nome pubblico è mostrato al cliente. Disponibile in Area Clienti consente il pagamento autonomo soltanto ai gateway che supportano questa opzione.

Il costo di mancato incasso e l’aliquota IVA preparano eventuali addebiti successivi. Le commissioni di incasso possono essere ribaltate con quota fissa e percentuale solo nei gateway previsti: verificare contratto e trasparenza prima di abilitarle.

Provider Stripe

Inserire chiave pubblica, chiave privata e signing secret del webhook dello stesso ambiente Stripe. Le chiavi test devono lavorare con webhook test e carte ufficiali di prova; produzione deve usare esclusivamente credenziali live. Non mescolare gli ambienti.

Registrare in Stripe l’endpoint webhook specifico dell’ISP e sottoscrivere gli eventi richiesti per checkout, Payment Intent, addebiti, rimborsi e dispute. Un redirect riuscito non registra da solo l’incasso: il webhook autenticato completa e riconcilia lo stato.

Cambiare account Stripe

Le autorizzazioni appartengono all’account Stripe che le ha create. Prima di sostituire le chiavi censire carte salvate, mandati SEPA, addebiti pendenti, rimborsi e webhook. Il comando Reset ID Stripe va usato soltanto in una migrazione pianificata.

I mandati SEPA possono essere ricreati dal flusso previsto, mentre le carte richiedono una nuova autorizzazione del cliente e non possono essere trasferite fra account Stripe. Informare gli utenti e verificare nuovamente tutti i metodi automatici.

Carta di credito Stripe

Questo è il pagamento iniziato dal cliente su una fattura. Configurare stato, Area Clienti, nomi, descrittore dell’estratto, gestione delle dispute e commissioni. Il descrittore deve rispettare i vincoli Stripe ed essere riconoscibile.

Il cliente apre il documento, avvia Checkout, inserisce la carta e torna al risultato. Considerare pagato il documento soltanto dopo conferma applicativa/webhook; richieste 3DS o stati intermedi non sono un incasso definitivo.

Addebito automatico su carta Stripe

Il gateway automatico usa un metodo carta salvato e autorizzato sul cliente. Prima il cliente completa il Setup Intent dall’Area Clienti, dalla scheda CRM o dal percorso contratto; ISP Billing conserva gli identificativi Stripe, non i dati completi della carta.

Alla fatturazione o scadenza il sistema tenta l’addebito secondo il processo configurato. Autenticazione richiesta, carta scaduta, fondi, blocco o metodo rimosso producono un esito da gestire; non sostituire il metodo senza consenso.

Addebito SEPA tramite Stripe

Il cliente autorizza un IBAN tramite il flusso Stripe e il gateway avvia la cattura automatica il numero di giorni configurato prima della scadenza. L’esito è asincrono e può richiedere diversi giorni lavorativi; una fattura in lavorazione non va marcata manualmente pagata.

Configurare descrittore, anticipo e gestione disputa. Conservare il mandato e attendere l’evento finale; insoluti e revoche devono generare la procedura amministrativa prevista.

Provider TS Pay

Inserire partita IVA e codice fiscale, ottenere il Merchant ID, avviare Autorizza API Key e completare il callback. Dopo l’autorizzazione verificare stato API Key, Webhook ID e secret. L’onboarding e la connessione sono completi soltanto quando l’app mostra gli identificativi attivi.

Proteggere API key e webhook secret. Il webhook specifico dell’ISP riceve stati di source e charge; non simulare esiti modificando fatture o record locali.

TS Pay manuale e automatico

Il gateway TS Pay manuale può offrire nell’Area Clienti carta, IBAN e PayPal secondo gli interruttori configurati. Nomi, descrittore e commissioni si applicano come negli altri gateway online.

TS Pay Card Auto e IBAN Auto usano metodi salvati e autorizzati. Associare il metodo corretto al cliente e verificare source attiva prima degli addebiti. Un’opzione disabilitata nel gateway manuale non elimina automaticamente i metodi già salvati.

SDD bancario e secondo flusso SDD

I gateway Addebito in conto SEPA generano flussi bancari, non chiamate Stripe. Configurare Creditor ID, partita IVA, nome, IBAN creditore, SIA/BIC, ABI, prefisso mandato, anticipo minimo, costo insoluto e IVA.

Attivare B2B soltanto per clienti business con mandato compatibile. L’opzione di separazione FRST e il prefisso mandato sono comuni ai gateway SDD: modificarli in uno influenza l’altro. Il secondo gateway permette un flusso distinto mantenendo queste regole condivise.

Bollettino postale

Configurare istruzioni, ragione sociale, conto postale, IBAN e codice di autorizzazione. La stampa PDF automatica richiede tutti i dati obbligatori e comporta il costo indicato nell’interfaccia per ogni bollettino generato.

Rendere il metodo visibile in Area Clienti solo se le istruzioni sono aggiornate. Il bollettino non conferma automaticamente l’incasso: il pagamento va riconciliato secondo il processo amministrativo.

Bonifico e metodi personalizzati

Bonifico mostra IBAN e istruzioni. I tre gateway personalizzati possono rappresentare metodi offline specifici dell’ISP, con nome pubblico, eventuale IBAN e istruzioni. Non usarli per fingere un provider online: non dispongono di webhook o conferma automatica.

Assegno, POS offline e contanti registrano un canale manuale; Nota credito identifica la compensazione tramite documento. Ogni incasso manuale deve riportare data, importo, riferimento e operatore.

Plafond rivenditore

Il gateway Plafond reseller è riservato ai flussi dell’area rivenditore: scala la disponibilità assegnata secondo le regole di plafond e non è un metodo generico da mostrare ai clienti finali. Prima dell’uso configurare rapporto, limite, movimenti e permessi del rivenditore.

Ogni utilizzo deve restare riconciliabile con ordine, documento e movimento di plafond. Un plafond insufficiente non va aggirato registrando un pagamento manuale diverso.

Metodi di pagamento del cliente

La scheda cliente e l’Area Clienti gestiscono carta Stripe, conto bancario Stripe, carta/IBAN TS Pay e conto bancario manuale secondo provider attivi. Il metodo predefinito può essere usato da contratti e automazioni.

Non conservare PAN, CVV o credenziali bancarie nei campi CRM. Eliminare un metodo interrompe gli addebiti futuri ma non annulla transazioni già avviate.

Webhook, rimborsi e dispute

Stripe gestisce checkout completato, Payment Intent, charge riuscita/fallita, fattura pagata, rimborso e chiusura disputa. TS Pay gestisce attivazione source e charge. Ogni evento deve essere verificato con il secret e processato in modo idempotente.

Un rimborso modifica la situazione economica ma non cancella la fattura originaria; dispute e insoluti possono generare costi da ribaltare se configurato. Riconciliare sempre documento, pagamento e riferimento provider.

Area Clienti e ricariche

Solo gateway attivi e autorizzati per l’Area Clienti vengono proposti sul documento. Il cliente sceglie il metodo, completa il percorso esterno o incorporato e vede il risultato. Per i servizi ricaricabili il pagamento riuscito della fattura aggiorna il periodo del servizio tramite il normale evento di incasso.

Non aggiornare manualmente la scadenza mentre il pagamento è in attesa. Se il webhook arriva in ritardo, controllare stato provider, evento e registrazione del pagamento.

Checklist completa

• Configurare prima il provider
• Usare credenziali dello stesso ambiente
• Registrare e verificare il webhook
• Attivare soltanto i gateway utilizzati
• Definire nomi pubblici e istruzioni
• Decidere visibilità Area Clienti
• Configurare dispute e commissioni
• Ottenere il consenso per metodi salvati
• Attendere gli esiti asincroni
• Configurare correttamente mandati SDD
• Riconciliare metodi offline manualmente
• Non memorizzare dati carta sensibili
• Verificare rimborsi e dispute
• Controllare il rinnovo dei servizi ricaricabili