Importazione da Stripe

Questa guida descrive l'importazione tramite file dei pagamenti Stripe mediante un modello di importazione: quali dati esportare, come configurare il modello e cosa viene generato dall'importazione. I dettagli dell'API sono disponibili nella sezione Importazioni di banche e pagamenti.

1. Esporta il file dei pagamenti da Stripe

Nel pannello di controllo di Stripe, apri Pagamenti (Payments) → Esporta (Export), seleziona l'intervallo di date, mantieni l'opzione Tutte le colonne (All columns) e includi le colonne di metadati che utilizzi (Stripe esporta ciascuna chiave di metadati come colonna denominata <key> (metadata), ad esempio orderNo (metadata)). Scarica il file CSV. Sia le esportazioni in modalità live che quelle in modalità test sono compatibili.

Le righe che non hanno movimentato denaro vengono ignorate durante l'importazione: tentativi di pagamento falliti, cancellati o che richiedono ancora un metodo di pagamento, e addebiti che non sono mai stati contabilizzati (captured).

2. Crea un conto bancario per Stripe

Ogni importazione confluisce in un conto bancario. Nella sezione Banca (Bank), fai clic su Nuovo conto bancario (New bank account), seleziona Tipo: Stripe (un conto Stripe non possiede un IBAN), assegna un nome (ad esempio "Stripe"), seleziona la valuta in cui fatturi e il relativo conto patrimoniale. Il saldo di Stripe si comporta come un conto bancario: gli addebiti entrano, le commissioni escono e i trasferimenti (payouts) spostano il saldo verso il tuo conto bancario reale.

3. Crea il modello di importazione

In Banca (Bank) → Modelli di importazione (Import templates), fai clic su Nuovo modello di importazione (New import template), seleziona il tipo Stripe e assegna un nome.

Campi (Fields). Ciascuna colonna dell'esportazione di Stripe corrisponde a una riga. La casella Obbligatorio nel file (Required in file) indica che la colonna deve essere presente nel file caricato; un file privo di una colonna obbligatoria viene rifiutato e i nomi mancanti vengono mostrati. Le 19 colonne relative alle carte (Card …) sono deselezionate per impostazione predefinita poiché Stripe le omette per alcuni account.

Conto contabile (Ledger account). Alle righe che movimentano denaro (Amount, Fee, Amount Refunded) può essere associato un conto contabile, sia uno esistente sia uno nuovo creato direttamente dalla stessa riga. Ogni movimento generato da un campo assegnato viene registrato al momento dell'importazione: il denaro in entrata addebita il conto bancario Stripe e accredita il conto assegnato, il denaro in uscita compie l'operazione inversa e la transazione bancaria viene contrassegnata come abbinata (matched) a quella registrazione di prima nota. La configurazione standard prevede:

Campo	Conto	Effetto
Fee	un conto costi per commissioni PSP (6800 nel piano dei conti standard)	Ogni commissione Stripe viene registrata come costo
Amount	lascia "Non registrato" (Not posted)	Gli addebiti rimangono aperti per l'abbinamento con le fatture (vedi punto 5)
Amount Refunded	lascia "Non registrato" (Not posted)	I rimborsi vengono gestiti tramite note di credito (vedi punto 5)

Crea clienti mancanti (Create missing customers). Seleziona questa opzione sulla riga Customer Email. Per ogni indirizzo email presente nel file a cui non corrisponde ancora alcun partner, viene creato un cliente: il nome viene tratto da Customer Description (o dall'email se vuoto), mentre l'indirizzo viene ricavato dalle colonne Card Address … quando presenti. I partner esistenti vengono riconosciuti tramite l'email, senza distinzione tra maiuscole e minuscole, evitando così qualsiasi duplicazione.

Crea partner Stripe (Create partner Stripe). Seleziona questa opzione sulla riga Fee. L'importazione crea un partner fornitore denominato Stripe una sola volta (eventuali partner esistenti con lo stesso nome vengono riutilizzati) e registra ogni movimento di commissione in prima nota indicando Stripe come partner, in modo che le registrazioni delle commissioni mostrino a chi è stato effettuato il pagamento.

Campi di metadati (Metadata fields). Aggiungi una riga per ciascuna chiave di metadati che desideri venga letta dall'importazione, ad esempio orderNo. Su queste righe è possibile impostare due flag:

• Crea o collega fatture (Create or link invoices): contrassegna la chiave che identifica un ordine (punto 5). Può essere associata a una sola riga. Accanto ad essa compare l'aliquota IVA per le fatture create e un Articolo di catalogo (Catalog item) opzionale: se selezionato, ogni riga di fattura creata dall'importazione farà riferimento a quel prodotto o servizio, in modo che i ricavi vengano contabilizzati sul conto dell'articolo; il testo della riga continuerà comunque a derivare dall'addebito.
• Flag azienda (Company flag): contrassegna una chiave il cui valore indica che l'acquirente è un'azienda (true, 1, yes, company, business oppure b2b). I clienti creati da tali addebiti saranno partner di tipo azienda, mentre tutti gli altri saranno persone fisiche.

Salva il modello.

4. Importa il file

Nella sezione Banca (Bank), seleziona il conto bancario Stripe, il modello e il file, quindi fai clic su Importa (Import). Il pulsante mostrerà un'icona di caricamento fino al completamento dell'operazione; un file di grandi dimensioni potrebbe richiedere alcuni minuti poiché le fatture vengono emesse una alla volta. La riga di riepilogo del risultato indicherà quante transazioni sono state importate, quante esistevano già, quanti movimenti sono stati registrati e quanti clienti, fatture e note di credito sono stati creati. Gli avvisi elencheranno gli ordini che non è stato possibile elaborare e il relativo motivo.

Ripetere l'importazione dello stesso file è sicuro: le transazioni vengono riconosciute tramite l'ID dell'addebito Stripe, i clienti tramite l'email e gli ordini tramite il valore dei loro metadati.

5. Cosa fa la funzione "Crea o collega fatture"

Gli addebiti e i rimborsi vengono raggruppati in base al valore della chiave di metadati scelta (il numero d'ordine).

• Se esiste già una fattura di vendita per quel valore (un ordine di vendita il cui riferimento esterno corrisponde a quel valore, oppure una fattura il cui numero coincide con esso), gli addebiti vengono abbinati ad essa come pagamenti.
• In caso contrario, viene creata una fattura di vendita per il cliente: una riga per ogni addebito, con il testo della riga dell'addebito e l'importo dell'addebito come prezzo IVA inclusa calcolato all'aliquota IVA del modello, datata alla data del primo addebito. La fattura viene emessa e contabilizzata immediatamente e gli addebiti vi vengono abbinati, risultando così quietanzati. Viene registrato un ordine di vendita con canale stripe associato al numero d'ordine, in modo che l'importazione successiva esegua un collegamento anziché una nuova creazione.
• Ciascun rimborso presente nel gruppo diventa una nota di credito emessa a storno di quella fattura per l'importo rimborsato, e la transazione di rimborso viene ad essa abbinata.

I gruppi privi di un'email cliente, con addebiti in valute diverse o la cui fattura esistente risulti ancora in bozza o già pagata vengono ignorati e inseriti nell'elenco degli avvisi. Le relative transazioni rimangono non abbinate nella sezione Banca (Bank) → Transazioni (Transactions).

I numeri delle fatture attingono alla serie dell'anno corrente anche per gli addebiti risalenti ad anni precedenti, evitando così che le importazioni storiche entrino in conflitto con i numeri esistenti.

6. I sei campi opzionali in fondo al modello

La maggior parte delle aziende lascia vuoti tutti e sei i campi e l'importazione funziona esattamente allo stesso modo. Essi sono previsti per due situazioni specifiche: la necessità di registrare le prenotazioni con carta come documenti, oppure la riscossione di somme che appartengono in parte a terzi.

Perché i menu a tendina appaiono vuoti

I tre menu a tendina relativi al "tipo di operazione" elencano i tipi di operazione creati dalla tua azienda nella sezione Contabilità (Account) → Tipi di operazione (Operation types). Se non ne hai creato alcuno, il menu a tendina sarà vuoto. Non si tratta di un errore; è sufficiente creare prima un tipo di operazione o lasciare il campo vuoto.

Il menu a tendina Campo metadati creditore (Lender metadata field) elenca i nomi delle colonne di metadati inseriti nell'elenco Campi metadati (Metadata fields) più in alto nello stesso modulo. Aggiungi prima un campo di metadati in quella sezione affinché compaia qui.

Etichetta rimborso parziale ed Etichetta rimborso totale

Quando l'importazione genera una nota di credito per un rimborso, questi campi definiscono la dicitura stampata nella parte superiore del PDF della nota di credito stessa.

Situazione	Dicitura utilizzata	Predefinito
Il rimborso è inferiore al totale della fattura	Etichetta rimborso parziale	DEPOZITAS
Il rimborso è pari al totale della fattura	Etichetta rimborso totale	ANULIAVIMAS

Modificali solo se la tua azienda prevede diciture differenti su tali documenti. Essi non influiscono sulla numerazione né sulla contabilità.

Tipo di operazione di autorizzazione

Un'autorizzazione con carta rappresenta una somma di denaro bloccata sulla carta del cliente che non è stata ancora incassata. Nell'esportazione di Stripe, queste righe presentano il campo Captured impostato su false. Per impostazione predefinita, l'importazione le ignora poiché non vi è stato alcun movimento di denaro.

Compilando questo campo, ciascuna di queste righe diventerà un documento di vendita emesso, utilizzando il tipo di operazione specificato e la serie di documenti ad esso associata. Se lasciato vuoto, tali righe verranno ignorate e il risultato dell'importazione mostrerà l'avviso "authorization(s) skipped: template has no authorization operation type" (autorizzazione/i saltata/e: il modello non ha alcun tipo di operazione di autorizzazione).

A meno che la tua attività non richieda specificamente di mostrare le prenotazioni di fondi come documenti contabili, lascia il campo vuoto.

Tipo di operazione di payout, Tipo di operazione di commissione e Campo metadati creditore

Salta completamente questa sezione a meno che la tua azienda non incassi somme di denaro spettanti a terzi, come nel caso di un marketplace che paga i venditori o di una piattaforma che remunera i finanziatori. Un negozio tradizionale non compila mai questi campi.

Stripe gestisce queste informazioni suddividendole in due file. L'esportazione dei pagamenti indica quanto versato da ciascun cliente. Un'esportazione separata dei trasferimenti specifica quale quota di tali importi è stata girata all'altra parte. L'importazione necessita di entrambi i file per determinare la somma trattenuta.

Nella sezione Banca (Bank), il modulo di importazione mostrerà il campo per il file Esportazione trasferimenti Stripe (Stripe transfers export) non appena sarà presente almeno un modello Stripe; seleziona il file dei trasferimenti accanto a quello dei pagamenti. Tramite API corrisponde al campo transfersCsv di bank/statements/import.

Quando entrambi i file sono presenti:

Campo	Funzione
Tipo di operazione di payout (Payout operation type)	Per ciascun trasferimento verso l'altra parte, viene registrata una scrittura contabile per l'importo trasferito. I conti di dare e avere derivano da questo tipo di operazione. Se lasciato vuoto, la registrazione utilizzerà invece le regole di contabilizzazione relative ai debiti verso venditori e fornitori.
Tipo di operazione di commissione (Commission operation type)	La quota trattenuta, calcolata come importo dell'addebito meno la commissione Stripe meno l'importo trasferito, registrata solo se superiore a zero. I conti derivano da questo tipo di operazione o, in alternativa, dalle regole di contabilizzazione relative ai debiti verso venditori e ai ricavi da commissioni.
Campo metadati creditore (Lender metadata field)	Il nome della colonna dei metadati di Stripe che indica il destinatario dei fondi. Verrà creato un partner corrispondente a tale valore (o riutilizzato se già esistente) e impostato su entrambe le registrazioni di cui sopra. Se lasciato vuoto o in presenza di una riga priva del valore, verrà generato l'avviso "lender not identified" (creditore non identificato) e la registrazione verrà creata senza l'associazione a un partner.

Se entrambi i campi relativi al tipo di operazione vengono lasciati vuoti, non verrà generata alcuna scrittura di trasferimento o commissione, indipendentemente dalle altre impostazioni.

7. Trasferimenti verso il tuo conto bancario (Payouts)

L'esportazione dei pagamenti non include le righe relative ai payout, pertanto il denaro inviato da Stripe al tuo conto bancario reale viene contabilizzato a partire dal report dei payout. Nel pannello di controllo di Stripe, apri Report (Reports) → Payouts → Riconciliazione payout dettagliata (Payout reconciliation, itemized), scaricalo e importalo nella sezione Banca (Bank) → Liquidazioni (Settlements) sul tuo conto bancario reale, quindi registra ciascun payout.

Per ogni riga di payout il cui addebito, commissione o rimborso sia già stato associato al conto bancario Stripe da questa importazione, la contabilizzazione sposterà l'importo netto della riga dal conto bancario Stripe al conto bancario reale. Le commissioni e i pagamenti delle fatture non verranno registrati una seconda volta. Le righe liquidate da Stripe che questa importazione non ha intercettato verranno registrate secondo le modalità descritte in Importazioni di banche e pagamenti.

Ciascun payout mostra il campo Differenza rispetto ai pagamenti importati (Difference to imported payments): la somma movimentata dal payout meno l'importo detenuto sul conto bancario Stripe per i medesimi addebiti e rimborsi. Un valore pari a zero indica che il payout azzera il saldo del conto Stripe. Una riga che presenta una differenza, oppure un movimento sul conto Stripe non ancora contabilizzato, viene conteggiata nella sezione Righe da controllare (Lines to check). Poiché l'esportazione dei pagamenti memorizza unicamente il totale rimborsato per ciascun addebito, tutte le righe di rimborso relative a uno stesso addebito vengono confrontate complessivamente con tale totale.

Se un payout è stato contabilizzato prima dell'importazione del file dei pagamenti, l'importazione ignorerà gli addebiti, le commissioni e i rimborsi associati a quel payout e ne riporterà il dettaglio negli avvisi.

8. Dove verificare i risultati

• Banca (Bank) → Transazioni (Transactions): ogni movimento importato; quelli abbinati si collegano alla fattura o alla registrazione di prima nota.
• Fatture (Invoices): fatture e note di credito create, con il numero d'ordine riportato nelle note.
• Partner (Partners): clienti creati.
• Contabilità (Ledger) → Prima nota (Journal): le registrazioni relative a commissioni, pagamenti e fatture.

Fatturazione (Billing)

File fino a 10 MB e 50.000 movimenti. Ogni 10 movimenti importati equivale a una richiesta API.