Gateway di pagamento: configurazione completa

Provider e gateway non sono la stessa cosa

Il provider contiene la connessione tecnica a Stripe, TS Pay o PAAV. 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 o riconciliazione e infine associare metodi ai clienti. Disattivare il provider blocca nuove operazioni e nasconde i gateway dipendenti; gli esiti PAAV già avviati continuano a essere riconciliati.

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.

Sotto il nome di ogni gateway sono sempre visibili tre conteggi: clienti che lo usano come modalità predefinita, servizi non terminati che lo hanno impostato e fatture aperte negli stati Da pagare o Pagamento in corso. I valori sono informativi e non modificano clienti, servizi o documenti.

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.

Trasferire massivamente gli utilizzi SEPA

Le schede Addebito SEPA (Stripe), Addebito in conto (SEPA) e Addebito SEPA (PAAV) permettono di trasferire separatamente clienti predefiniti, servizi non terminati e fatture aperte verso un altro dei tre gateway attivo. Aprire la scheda, scegliere l’ambito, selezionare la destinazione e controllare l’anteprima prima di confermare.

Il trasferimento cambia soltanto il gateway e conserva il metodo bancario e l’IBAN. Sono esclusi i record senza conto bancario valido; per le fatture sono esclusi anche addebiti sospesi e pagamenti, rate, catture o disposizioni già in lavorazione. L’operazione non disattiva il gateway sorgente, non include il secondo gateway SDD e non chiama i provider durante il cambio.

Eseguire un ambito alla volta, rileggere i conteggi dopo ogni operazione e controllare le esclusioni prima di decidere eventuali correzioni manuali. Il trasferimento richiede i permessi di scrittura CRM ed è registrato nei log dell’account.

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.

Provider PAAV e addebito SEPA automatico

PAAV è un ecosistema di servizi di pagamento per imprese nato dall’esperienza di Stantup Service. Nell’integrazione con ISP Billing gestisce mandati e disposizioni di addebito diretto SEPA. I servizi di pagamento sono forniti tramite Treezor SAS; PAAV opera come agente autorizzato e non è una banca.

In Provider di pagamento → PAAV scegliere Abilitato, inserire Client ID, Client secret e Base URL dell’ambiente corretto, quindi configurare il gateway PAAV SEPA Auto. I giorni di anticipo non possono essere inferiori a quattro. La disposizione automatica viene inviata con l’anticipo configurato e mantiene la scadenza come data programmata. Se una cattura manuale o un documento con scadenza ravvicinata non dispone dell’intero preavviso, la data programmata viene spostata in avanti per garantirlo. Il pagamento viene registrato soltanto quando risulta completato. Gli eventuali storni e gli esiti delle disposizioni già avviate continuano a essere rilevati anche se il provider viene successivamente disabilitato. Quando viene rilevato un addebito fallito o annullato, la fattura mostra l’esito e, se disponibili, il codice e la motivazione comunicati da PAAV, con la data di aggiornamento. Il mancato incasso compare anche nei Log errori e nell’avviso della dashboard; l’addebito resta sospeso. Prima di usare Abilita addebito o Cattura pagamento, verificare e risolvere la causa indicata.

La disabilitazione impedisce nuove disposizioni e nasconde il gateway PAAV dalla configurazione, senza cancellare credenziali, mandati o storico. Per informazioni commerciali e sul servizio consultare il sito ufficiale PAAV.

Mandato PAAV: dati, data firma e stato

Compilare il campo BIC / SWIFT con il codice fornito dalla banca. Il conto può essere salvato anche senza questo dato: quando serve creare un mandato PAAV, ISP Billing prova a recuperarlo e lo conserva sul conto per gli utilizzi successivi. Se il mandato è già utilizzabile oppure il BIC è presente, il recupero non è necessario. Se compare un messaggio di attesa, riprovare la cattura tra poco; se il BIC non è recuperabile, inserirlo manualmente. Il recupero del BIC non conferma l’esito del pagamento.

L’IBAN non può essere modificato dopo il salvataggio. Per cambiare conto, creare un nuovo metodo di pagamento, aggiornare i collegamenti a servizi e fatture e rimuovere il precedente quando consentito. Un conto ancora collegato a servizi o documenti aperti può impedire la rimozione.

Prima del primo addebito completare sul conto bancario intestatario, IBAN, indirizzo e data effettiva di accettazione; verificare anche codice fiscale o partita IVA. La data firma comunicata a PAAV proviene dalla data di accettazione salvata sul conto: può quindi essere precedente alla registrazione in PAAV. Una data mancante, non valida o futura deve essere corretta; non viene sostituita con la data odierna.

Un mandato recuperato deve corrispondere al conto e alla tipologia SEPA selezionati. Se risulta chiuso, revocato, incompatibile o con uno stato non riconosciuto, la richiesta viene fermata e viene mostrato un errore. Lo stato riportato nella lista Mandati è l’ultimo stato salvato e può non coincidere con quello attuale in PAAV. Lo stato in attesa non dimostra che il mandato sia assente e non garantisce l’esito dell’addebito.

Se PAAV segnala Nessun mandato, controllare sia il mandato sia il dettaglio dell’operazione e comunicare all’assistenza PAAV il codice e la motivazione dell’esito. La presenza del mandato nell’elenco, da sola, non spiega il rifiuto. Verificare con PAAV le condizioni per riutilizzare un mandato precedente prima di ripetere il pagamento. Gli esiti registrati prima di questo aggiornamento possono avere soltanto una descrizione generica: le motivazioni non precedentemente conservate non vengono ricostruite.

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.

Il collegamento Paga ora segue il gateway già impostato sulla fattura: con Carta di credito (Stripe) o TS Pay apre direttamente il checkout del provider; con un metodo diverso apre la pagina di pagamento protetta dell’Area Clienti. In quest’ultimo caso il cliente deve autenticarsi se non ha già effettuato l’accesso. Il collegamento non sceglie automaticamente un gateway carta diverso da quello assegnato al documento.

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