Nordlet

← Documentazione / Guide

Importazioni bancarie e di pagamenti

Estratti conto camt.053, CSV di Stripe, riconciliazione dei pagamenti PSP e flussi JSON personalizzati.

Tutte le importazioni vengono registrate come movimenti bancari su un conto corrente (bank/accounts/create). I movimenti dispongono di un externalId; la reimportazione dello stesso file è sicura, in quanto le righe la cui combinazione (bankAccountId, externalId) esiste già vengono ignorate e conteggiate nel contatore skipped. I movimenti importati partono con lo stato new e vengono registrati nel libro mastro (ledger) solo quando associati (bank/transactions/match, utilizzando bank/transactions/suggest-matches per i candidati).

L'applicazione web espone le stesse importazioni alla voce Banca → Importa file (caricamento file, selettore di modelli).

Un'associazione errata può essere annullata tramite bank/transactions/unmatch (Annulla associazione in Banca → Movimenti). Le registrazioni contabilizzate non vengono mai modificate o eliminate: un pagamento associato a una fattura, oppure una riga contabilizzata da un modello di importazione su un conto, genera una transazione di storno con ogni voce sul lato opposto, datata date (valore predefinito: oggi, e mai antecedente alla registrazione originale). L'importo pagato e lo stato del pagamento della fattura vengono ripristinati sottraendo l'importo di quella riga bancaria. Una riga collegata a un regolamento di un fornitore di servizi di pagamento (PSP) viene semplicemente scollegata, poiché la registrazione del regolamento appartiene al lotto. La riga torna allo stato new e può essere associata nuovamente. La data di storno deve ricadere in un periodo contabile aperto.

Modelli di importazione

Un modello di importazione definisce una fonte dati, elenca i campi forniti dalla fonte e mappa i campi di importo monetario sui conti del libro mastro. I modelli sono gestiti nella sezione Banca → Modelli di importazione e tramite gli endpoint bank/import-templates/create|update|delete|get|list.

POST /v1/bank/import-templates/create
{
  "name": "Stripe payments export",
  "type": "stripe",
  "fields": [
    { "name": "id" },
    { "name": "Created date (UTC)" },
    { "name": "Amount" },
    { "name": "Fee", "accountCode": "6800" },
    { "name": "Amount Refunded" }
  ],
  "metaFields": ["order_id"]
}
  • type può essere stripe, iso20022, bank_connection o revolut.
  • Ciascun campo possiede un name e un eventuale accountCode. Solo i campi che movimentano denaro accettano un conto: Amount, Fee e Amount Refunded per Stripe; Ntry/Amt per il camt.053; transaction_amount.amount per il feed bancario. Il conto deve esistere nel piano dei conti (crealo tramite ledger/accounts/create).
  • Il parametro fields può essere omesso; in tal caso, vengono usati i campi predefiniti del tipo corrispondente: i nomi delle colonne del file di esportazione Pagamenti → Esportazione di Stripe (escluse le 19 colonne Card …, che anche il modulo lascia deselezionate per impostazione predefinita), gli elementi camt.053 presenti in ogni estratto conto (Stmt/Id, Stmt/Acct/Id/IBAN, Stmt/Bal/…, Ntry/Amt, Ntry/CdtDbtInd, Ntry/Sts, Ntry/BookgDt) o gli attributi restituiti per transazione da un feed bancario PSD2. Aggiungi o rimuovi voci per adattarle al tuo file: l'importatore legge anche gli elementi camt.053 opzionali Ntry/ValDt, Ntry/NtryRef, Ntry/AcctSvcrRef, Ntry/AddtlNtryInf, TxDtls/Refs/EndToEndId, TxDtls/Refs/TxId, TxDtls/RltdPties/Dbtr/Nm, TxDtls/RltdPties/DbtrAcct/Id/IBAN, TxDtls/RltdPties/Cdtr/Nm, TxDtls/RltdPties/CdtrAcct/Id/IBAN, TxDtls/RmtInf/Ustrd e TxDtls/AddtlTxInf.
  • Un campo Customer Email di Stripe può includere "createPartner": true. In questo caso, l'importazione crea un cliente (partner di tipo persona, contrassegnato come cliente) per ogni indirizzo email nel file che non corrisponde ad alcun partner esistente, utilizzando Customer Description come nome (o l'indirizzo email se vuoto) e le colonne Card Address … come indirizzo, qualora presenti nel file. I partner esistenti vengono riconosciuti tramite l'indirizzo email, senza distinzione tra maiuscole e minuscole. La risposta restituisce il conteggio in customersCreated.
  • metaFields (solo per Stripe) elenca le chiavi di metadati associate ai tuoi addebiti. Stripe esporta ciascuna chiave come colonna <key> (metadata); l'elenco è a formato libero e può essere esteso.
  • invoiceItemId (solo per Stripe, opzionale) rappresenta un articolo di catalogo. Se impostato, ogni riga di fattura e nota di credito creata dall'importazione fa riferimento a tale articolo (la sua registrazione contabile e, se invoiceVatRatePercent è vuoto, la sua aliquota IVA); il testo della riga continua a derivare dall'addebito.
  • companyMetaField (solo per Stripe) indica una di queste chiavi come flag aziendale. Quando un addebito riporta true, 1, yes, company, business o b2b in quella colonna, il cliente creato viene registrato come partner di tipo azienda anziché persona.
  • invoiceMetaField (solo per Stripe) indica una di queste chiavi (ad esempio un numero d'ordine), mentre invoiceVatRatePercent definisce l'aliquota IVA per le fatture generate. Durante l'importazione, ogni riga di addebito e rimborso viene raggruppata in base al valore di tale chiave:
    • un valore corrispondente a una fattura di vendita esistente (un ordine di vendita il cui externalRef corrisponde a quel valore, tramite ecommerce/orders/create per qualsiasi canale, oppure una fattura il cui fullNumber corrisponde a quel valore) collega il gruppo a tale fattura;
    • un valore privo di fattura corrispondente ne crea una nuova: partner derivato da Customer Email (creato se mancante, come per createPartner), una riga per addebito (Checkout Line Item Summary o Description come testo, l'importo dell'addebito come prezzo IVA inclusa basato su invoiceVatRatePercent), data di emissione pari alla data del primo addebito, trattamento IVA basato sull'azienda e sul paese della carta. La fattura viene emessa e contabilizzata immediatamente, e viene registrato un ordine di vendita con canale stripe e quel valore come externalRef, in modo che le importazioni successive effettuino il collegamento anziché creare nuove fatture;
    • ogni addebito all'interno del gruppo viene quindi associato alla fattura come pagamento (registrando l'incasso); ciascun rimborso genera una nota di credito emessa a storno della fattura per l'importo rimborsato e vi viene associato. I conteggi vengono restituiti nei campi invoicesCreated, invoicesLinked, creditNotesCreated e paymentsMatched; i gruppi che non è stato possibile elaborare (assenza di email del cliente, valute miste, fattura collegata ancora in stato di bozza o già interamente pagata) vengono elencati in warnings e lasciati come movimenti bancari in stato new. Non associare inoltre Amount a un conto del libro mastro nello stesso modello: un addebito associato a una fattura non viene contabilizzato una seconda volta, mentre un addebito non associato lo sarebbe.
  • I nomi dei modelli sono unici per ciascuna azienda.
  • I modelli camt.053 e per connessioni bancarie offrono le stesse opzioni, lette dall'estratto conto anziché dalle colonne di Stripe:
    • Creazione dei partner mancanti: l'opzione createPartner sulla riga del nome del debitore (TxDtls/RltdPties/Dbtr/Nm, feed debtor.name) crea un cliente per ogni pagatore sconosciuto di somme in entrata; sulla riga del nome del creditore (TxDtls/RltdPties/Cdtr/Nm, feed creditor.name) crea un fornitore per ogni beneficiario sconosciuto di somme in uscita. I partner vengono identificati tramite IBAN (memorizzato in partner_bank_accounts) e successivamente per nome esatto; un nuovo partner viene classificato come azienda se il nome contiene una forma giuridica (UAB, MB, SIA, GmbH, Ltd, ecc.), altrimenti come persona fisica. Il conteggio viene restituito in customersCreated (importazione file) o partnersCreated (sincronizzazione feed).
    • Collegamento fatture per riferimento: l'opzione invoiceMetaField impostata su una riga di causale o riferimento (TxDtls/RmtInf/Ustrd, TxDtls/RmtInf/Strd/CdtrRefInf/Ref, TxDtls/Refs/EndToEndId; feed remittance_information, reference_number) associa ogni nuova riga bancaria il cui riferimento, la cui causale o descrizione contenga il numero di una fattura di vendita emessa aperta (denaro in entrata) o di una fattura d'acquisto registrata (denaro in uscita), e ne contabilizza il pagamento. Se l'IBAN del pagatore è memorizzato per un partner, o se il nome del pagatore coincide con il nome o il codice di un partner, la fattura deve appartenere a tale partner. Un pagamento proveniente da un pagatore sconosciuto viene collegato solo se corrisponde esattamente al saldo residuo della fattura e se il numero della fattura include il prefisso della sua serie, evitando che un numero isolato, come un importo, venga interpretato erroneamente come riferimento. Un pagamento superiore al saldo residuo non viene mai collegato. Le righe che non superano questi controlli rimangono nello stato new per l'associazione manuale e vengono elencate negli avvisi (warnings). Con advanceInvoices: true, un pagamento in entrata non associato proveniente da un partner noto genera una fattura d'acconto emessa (tipo advance) per l'importo calcolato in base a invoiceVatRatePercent o all'aliquota di invoiceItemId e vi associa il pagamento; il partner deve essere noto, pertanto è necessario selezionare anche la riga del debitore.
    • Regole di contabilizzazione per codice transazione: oltre a Ntry/Amt / transaction_amount.amount, l'elenco dei campi supporta righe di regola come Ntry/BkTxCd=CHRG, =INTR, =TAXE, Ntry/CdtDbtInd=DBIT, =CRDT (feed: bank_transaction_code=…, credit_debit_indicator=…). Una riga viene contabilizzata sul conto della prima regola corrispondente: prima la famiglia del codice transazione bancaria, poi la direzione e infine la riga dell'importo semplice. Le righe di regola non vengono verificate rispetto al file.
    • Partner per oneri bancari: l'opzione createPartner sulla riga di regola …=CHRG crea un fornitore denominato come la banca (dall'estratto conto Stmt/Acct/Svcr/FinInstnId/Nm, dalla banca della connessione o dal nome del conto bancario nel libro mastro) e registra ogni onere associandolo a tale partner.
    • I modelli per connessioni bancarie vengono associati a ciascun conto tramite bank/feeds/accounts/configure (Banca → Connessioni nell'applicazione), che definisce anche la frequenza di sincronizzazione syncSchedule (manual, daily, weekly, monthly): l'API sincronizza autonomamente i conti associati a una pianificazione una volta trascorso il periodo di riferimento. I modelli vengono applicati a ogni chiamata di bank/feeds/sync; la risposta della sincronizzazione restituisce inoltre i contatori posted, partnersCreated, invoicesLinked, invoicesCreated, paymentsMatched e warnings.

Passa templateId a bank/statements/import anziché format: il tipo del modello determina il parser, e il file deve contenere tutti i campi elencati nel modello. L'assenza anche di un solo campo comporta il rifiuto della richiesta con codice HTTP 422 e l'indicazione dei nomi delle colonne o degli elementi mancanti. I campi di metadati non sono obbligatori. I modelli per connessioni bancarie descrivono un feed PSD2 attivo e non possono essere utilizzati per l'importazione di file.

Un modello ISO 20022 è in grado di leggere anche file MT940: un file che inizia con {1: o :20: (o inviato con "format": "mt940") viene analizzato come MT940 e le regole di corrispondenza dei riferimenti e di contabilizzazione del modello vengono applicate alle relative righe. Il controllo degli elementi viene ignorato per il formato MT940, e le regole Ntry/BkTxCd=… non si applicano alle righe MT940 poiché quest'ultimo non trasporta codici di transazione bancaria ISO 20022; utilizzare invece le regole Ntry/CdtDbtInd=….

Un conto bancario gestisce una sola valuta. Un estratto conto in un'altra valuta viene rifiutato con codice HTTP 422 (in un file camt.053 contenente estratti conto in valute diverse per lo stesso IBAN, viene importato esclusivamente l'estratto conto espresso nella valuta del conto), così come una riga inviata a bank/transactions/import con una currency diversa da quella del conto.

Ogni movimento generato da un campo associato a un accountCode viene registrato al momento dell'importazione come un'unica transazione di prima nota: l'entrata di denaro addebita il conto contabile della banca e accredita il conto mappato; l'uscita di denaro addebita il conto mappato e accredita il conto contabile della banca. Gli importi vengono convertiti nella valuta di base alla data del movimento. Il movimento bancario viene quindi associato (matched) alla transazione di prima nota (matchedDocumentType = journal_transaction) e non viene più proposto per l'associazione alle fatture. La risposta riporta il conteggio in posted. I movimenti derivanti da campi non mappati rimangono nello stato new e vengono associati alle fatture come in precedenza; ad esempio, è possibile mappare Fee sul conto dei costi per commissioni PSP e lasciare Amount non mappato, in modo che gli addebiti continuino a essere associati alle fatture di vendita.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "…",
  "content": "id,Created date (UTC),Amount,…"
}

ISO 20022 camt.053 (XML per l'open banking)

Le banche lituane (Swedbank, SEB, Luminor, Šiaulių bankas, ecc.) consentono di scaricare gli estratti conto in formato XML camt.053 ISO 20022 dall'internet banking, solitamente nella sezione di esportazione/download degli estratti conto, selezionando il formato "ISO XML" o "camt.053". Lo stesso formato viene restituito dalle API di informazioni sui conti PSD2.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "camt053",
  "content": "<?xml version=\"1.0\"…>…"
}
  • Un file può contenere più estratti conto; l'IBAN di ciascun estratto conto deve corrispondere all'IBAN del conto bancario (gli estratti conto privi di IBAN, o relativi a conti che ne sono sprovvisti, vengono accettati così come sono).
  • I riferimenti dei movimenti (AcctSvcrRef/NtryRef, con fallback su un hash del contenuto) diventano l'externalId.
  • La risposta restituisce i metadati relativi a ciascun estratto conto: identificativo, periodo, saldi iniziali e finali, numero di movimenti.
  • Nome della controparte, IBAN e causale di pagamento vengono estratti per ciascun movimento al fine di consentirne l'associazione.

I pagamenti nella direzione opposta vengono esportati in formato pain.001 tramite bank/payments/export.

Revolut Business CSV

Scarica l'estratto conto dei movimenti di un conto Revolut Business in formato CSV e importalo utilizzando il modello predefinito Revolut Business (templateId: "builtin-revolut"). Questo modello è disponibile per ogni azienda senza necessità di creazione: bank/import-templates/list-builtin lo elenca, bank/import-templates/get lo restituisce, mentre bank/import-templates/update e bank/import-templates/delete lo rifiutano restituendo un errore HTTP 400. Nell'applicazione, il modello viene mostrato per primo nella sezione Banca → Modelli di importazione; aprendolo è possibile visualizzarne le impostazioni, e il salvataggio genera un modello aziendale personalizzato modificabile dall'utente.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "builtin-revolut",
  "content": "Date started (UTC),Date completed (UTC),ID,Type,State,…"
}
  • Vengono importate esclusivamente le righe con State = COMPLETED. Le altre righe (ad esempio PENDING) vengono escluse e conteggiate in warnings; saranno importate successivamente tramite un file in cui risulteranno completate.
  • Ciascuna riga genera un movimento bancario con la data tratta da Date completed (UTC), l'importo da Total amount, la valuta da Payment currency, l'identificativo ID come externalId e la descrizione da Description.
  • La controparte per i pagamenti in uscita è costituita da Beneficiary name e Beneficiary IBAN; per i pagamenti con carta privi di beneficiario, viene utilizzato l'esercente indicato in Description. La controparte per i pagamenti in entrata è formata da Sender name e Sender account.
  • Le righe vengono raggruppate per conto e valuta. Il campo International account number deve corrispondere all'IBAN del conto bancario, e vengono importate solo le righe espresse nella valuta del conto.
  • Per ogni riga l'importatore verifica che il saldo della riga precedente incrementato di Total amount corrisponda al campo Balance, inserendo in warnings le righe per le quali tale verifica fallisce.
  • Il file deve contenere le colonne Date completed (UTC), ID, Type, State, Description, Payment currency, Total amount, Reference, Sender name e Beneficiary name.

A ogni importazione, il modello predefinito esegue le seguenti operazioni:

  • crea un cliente per ogni mittente sconosciuto di somme in entrata e un fornitore per ogni beneficiario o esercente di carte sconosciuto per le somme in uscita, secondo quanto descritto nella sezione Creazione dei partner mancanti precedente;

  • associa ogni riga il cui campo Reference o Description contiene il numero di una fattura di vendita o d'acquisto aperta, contabilizzando il pagamento nel rispetto dei controlli descritti nella sezione Collegamento fatture per riferimento precedente;

  • contabilizza le righe non associate ad alcuna fattura in base al loro Type, sul conto definito dalla regola di contabilizzazione corrispondente:

    Type Regola di contabilizzazione Conto predefinito Piano dei conti (Romania) Registrazione
    FEE bank.fees 6800 627 addebita il conto della regola, accredita il conto contabile della banca; partner: un fornitore denominato come il conto bancario
    CARD_PAYMENT bank.cardPayments 6209 628 addebita il conto della regola, accredita il conto contabile della banca, senza IVA
    TOPUP bank.topUps 3010 1012 addebita il conto contabile della banca, accredita il conto della regola

    Le righe di altri tipi, come TRANSFER, rimangono nello stato new per la successiva associazione.

È possibile modificare i conti associati tramite ledger/posting-rules/update; il modello predefinito utilizzerà i nuovi conti a partire dall'importazione successiva. Una regola di contabilizzazione non può essere disattivata: per importare pagamenti con carta o ricariche senza contabilizzarli, crea un modello aziendale di tipo revolut privo delle righe Type=CARD_PAYMENT o Type=TOPUP ed effettua l'importazione con quello. Un pagamento con carta contabilizzato in questo modo non viene associato alla fattura del fornitore se questa viene registrata successivamente; è necessario registrarne solo una delle due, non entrambe.

Un modello aziendale di tipo revolut utilizza le stesse colonne e può contabilizzare le righe per tipo avvalendosi delle righe di regola Type=FEE, Type=CARD_PAYMENT, Type=TRANSFER e Type=TOPUP. L'importazione eseguita specificando "format": "revolut-csv" senza alcun modello importa le righe senza applicare nessuna di queste elaborazioni.

CSV di Stripe

Esporta i dati dal pannello di controllo di Stripe utilizzando uno dei report disponibili:

  • Rapporti → Saldo → Variazione dettagliata del saldo da attività (consigliato): colonne balance_transaction_id, created_utc, currency, gross, fee, net, reporting_category, description.
  • Pagamenti → Esportazione: colonne id, Created (UTC), Amount, Fee, Currency, Description, Customer Description.
POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "stripe-csv",
  "content": "balance_transaction_id,created_utc,currency,gross,fee,net,…"
}

Crea un conto bancario dedicato per Stripe (ad esempio denominato "Stripe", con conto di mastro 2710 o un apposito sottoconto): il saldo di Stripe si comporta come un conto bancario, in cui gli addebiti affluiscono, le commissioni vengono detratte e i trasferimenti (payout) spostano il saldo sul tuo vero conto bancario.

Comportamento in fase di importazione:

  • Ciascuna transazione di saldo genera un movimento bancario per l'importo lordo (externalId = identificativo della transazione di saldo).
  • Una commissione (fee) di importo diverso da zero genera un secondo movimento di segno opposto (externalId = <id>:fee, controparte "Stripe"), consentendo di registrare o associare le commissioni come costi separatamente dai ricavi. Le commissioni stornate sui rimborsi vengono importate come importi positivi.
  • Le righe di trasferimento (payout) vengono importate come singoli movimenti negativi; vanno associate alla corrispondente transazione in entrata sull'estratto conto del tuo vero conto bancario.
  • Le righe con importo pari a zero vengono ignorate; la data è estratta da created_utc (in formato UTC).
  • Le righe di esportazione dei pagamenti che non hanno movimentato denaro vengono ignorate: Captured = false (autorizzazioni o catture ritardate) e Status pari a Failed/Canceled.
  • Un importo rimborsato (Amount Refunded) diverso da zero genera un terzo movimento negativo (externalId = <id>:refund) datato Refunded date (UTC), in modo da non perdere i rimborsi parziali o totali inclusi nelle righe di pagamento.

Riconciliazione dei pagamenti PSP (report dei payout di Stripe)

Per suddividere un versamento cumulativo (payout) nei singoli ordini, rimborsi, commissioni e chargeback sottostanti, utilizza gli endpoint di regolamento anziché la semplice importazione dell'estratto conto. Sono supportati due formati di esportazione di Stripe (rilevati automaticamente):

  • Rapporti → Payouts → Riconciliazione dei payout, dettagliata (tipi di report payout_reconciliation.itemized.* o payout_reconciliation.by_id.itemized.*): report puntuale, una riga per transazione di saldo; preferito sui conti reali in produzione.
  • Pagamenti → Esportazione (pagamenti unificati): l'esportazione a livello di singolo addebito; utilizzabile in modalità test/sandbox dove la riconciliazione dei payout non è disponibile. Gli addebiti contabilizzati vengono raggruppati in base all'identificativo del payout nella colonna Transfer; le righe non contabilizzate o non andate a buon fine vengono saltate (skippedNotSettled); un importo rimborsato (Amount Refunded) diverso da zero genera una riga di rimborso sintetica all'interno del lotto di payout dell'addebito (un'approssimazione, poiché il rimborso potrebbe essersi effettivamente regolato in un payout successivo). I riferimenti per l'associazione derivano dall'identificativo dell'addebito (charge_id), da PaymentIntent ID, Invoice Number, Client Reference ID e da ciascuna colonna … (metadata) (ad esempio, un numero d'ordine nei metadati).

Un singolo file CSV può estendersi su più payout. Stripe scarica il report dettagliato un file per ciascuna sezione (…_charge_…, …_refund_…, …_fee_…); importali tutti: le righe relative a un payout già importato si fondono nel lotto esistente (segnalato nel contatore updated) a condizione che questo non sia stato ancora contabilizzato, e i totali del lotto vengono ricalcolati.

POST /v1/bank/settlements/import
{
  "bankAccountId": "…",
  "provider": "stripe",
  "content": "balance_transaction_id,created_utc,…,reporting_category,…,automatic_payout_id,…"
}

Comportamento in fase di importazione:

  • Le righe vengono raggruppate in base al campo automatic_payout_id in lotti di regolamento (un lotto per ciascun payout), con i relativi totali lordi, di commissione e netti (la somma del campo net corrisponde all'importo accreditato in banca). La reimportazione di un payout viene saltata (contatore skipped). Le righe non ancora assegnate a un payout e le righe di tipo payout stesse vengono ignorate e conteggiate separatamente.
  • Ciascuna riga di addebito, rimborso o contestazione viene associata automaticamente a una fattura di vendita utilizzando, nell'ordine: il riferimento esterno di un ordine e-commerce (externalRef, ricavato da order_id, payment_intent_id, source_id, charge_id o da qualsiasi colonna *_metadata[...]), il numero completo di una fattura (fullNumber) presente in tali colonne e, limitatamente a rimborsi e chargeback, il charge_id di un addebito precedentemente associato (dello stesso file o di importazioni precedenti).
  • Verifica i risultati tramite bank/settlements/list o bank/settlements/get; correggi eventuali elementi residui con bank/settlements/match { lineId, invoiceId } (oppure invoiceId: null per rimuovere l'associazione).

La chiamata POST /v1/bank/settlements/post { id, date?, commissionPercent? } registra l'intero lotto come un'unica transazione di prima nota bilanciata e regola le fatture associate (tramite i webhook paidAmount/paymentStatus e sale_invoice.paid):

  • Addebita il conto contabile della banca per il payout netto; addebita le commissioni PSP (settlements.fees, valore predefinito 6800) per le commissioni trattenute e le relative righe di spesa.
  • Accredita i crediti commerciali (clienti) per ciascun addebito associato; i rimborsi e i chargeback effettuano lo storno contabile. L'applicazione è limitata all'importo residuo di ciascuna fattura; eventuali eccedenze confluiscono nel conto sospeso generando un avviso.
  • Addebiti non associati: se viene impostato commissionPercent, essi vengono suddivisi tra ricavi da commissioni (settlements.commissionRevenue, valore predefinito 5001) e un debito verso il venditore (settlements.sellerPayable, valore predefinito 4499), rispecchiando il flusso di marketplace in cui il denaro incassato appartiene prevalentemente ai venditori. In assenza di tale parametro, gli importi vengono parcheggiati sul conto di sospeso (settlements.suspense, valore predefinito 4440, acconti ricevuti).
  • Le righe di tipo platform_earning (commissioni sull'applicazione Stripe Connect) vengono contabilizzate nei ricavi da commissioni; le righe di tipo transfer (payout ai venditori collegati) riducono il debito verso il venditore.
  • Tutti e quattro i conti possono essere ridefiniti a livello aziendale tramite le regole di contabilizzazione (ledger/posting-rules).
  • Una riga il cui addebito, la cui commissione o il cui rimborso sia stato precedentemente importato su un altro conto bancario tramite l'esportazione dei pagamenti di Stripe (bank/statements/import) non viene imputata a commissioni, crediti o conti sospesi. Il suo importo netto viene invece accreditato sul conto contabile di quel conto bancario, in modo che il conto bancario Stripe si azzeri payout dopo payout. Il campo summary.clearedAmount indica il totale movimentato in questo modo; una riga il cui importo differisce da quello detenuto da tale conto viene menzionata in warnings. Se non rimangono importi da registrare, il lotto viene contabilizzato con journalTransactionId nullo.

Gli endpoint bank/settlements/list e /get restituiscono, per ciascun lotto, i valori clearedNet, clearingDifference (righe di payout sottraendo gli importi detenuti dall'altro conto bancario; pari a zero in caso di quadratura) e clearingOpenCount (righe che presentano una differenza o un movimento non contabilizzato); l'endpoint /get restituisce le stesse informazioni a livello di singola riga tramite i campi clearingBankAccountId, clearingBooked, clearingDifference e clearingUnposted. Le righe di rimborso relative a uno stesso addebito vengono confrontate congiuntamente, poiché l'esportazione dei pagamenti memorizza esclusivamente il totale rimborsato. Un'esportazione dei pagamenti di Stripe importata dopo la contabilizzazione del relativo payout esclude i movimenti di quel payout e li segnala in warnings.

L'IVA sulle commissioni viene fatturata separatamente (emettendo una fattura di commissione al venditore); la suddivisione contabile si limita ad allocare la liquidità incassata.

Payout in un'altra valuta

La prima nota viene sempre redatta nella valuta di base dell'azienda, ma un payout in una valuta differente viene contabilizzato automaticamente senza richiedere interventi manuali:

  • Il lotto viene convertito al tasso di cambio valido alla data di contabilizzazione (date, con fallback alla data del payout e infine alla data odierna). Il tasso utilizzato è quello definito dall'azienda per quella valuta (reference/exchange-rates/set), purché aggiornato almeno quanto quello ufficiale; in caso contrario, viene applicato l'ultimo tasso ufficiale disponibile alla data o prima di essa. Se non è disponibile alcun tasso per la data di riferimento o date precedenti, la chiamata fallisce restituendo il codice 422 e indicando la necessità di eseguire reference/exchange-rates/sync.
  • Ciascun conto viene convertito al tasso di cambio del lotto, ad eccezione dei crediti commerciali (clienti), i quali vengono stornati al tasso di cambio (fxRate) applicato al momento dell'emissione di ciascuna fattura. La differenza risultante tra i due tassi viene registrata sul conto bank.fxGain (valore predefinito 5803) o bank.fxLoss (valore predefinito 6803) a titolo di differenza di cambio realizzata, garantendo in tal modo il corretto bilanciamento della prima nota.
  • Il campo summary nella risposta restituisce il tasso di cambio fxRate applicato e la conseguente differenza di cambio exchangeDifference, e il lotto mantiene memorizzato il tasso di cambio utilizzato per la contabilizzazione. Una fattura associata la cui valuta differisce da quella del lotto non viene regolata: il relativo importo confluisce nel conto di sospeso generando un avviso.
  • Rimane attiva una limitazione di importazione: un singolo payout le cui righe comprendano valute miste viene rifiutato con codice 422, così come una reimportazione la cui valuta differisca da quella del lotto già memorizzato per quel payout.

Feed manuali o personalizzati

Qualsiasi altro flusso di dati può essere inviato come semplice JSON:

POST /v1/bank/transactions/import
{
  "bankAccountId": "…",
  "transactions": [
    { "date": "2026-07-01", "amount": "-25.00", "currency": "EUR",
      "counterpartyName": "…", "description": "…", "externalId": "unique-ref-1" }
  ]
}

Fornisci un externalId stabile per ciascun movimento al fine di preservare l'idempotenza delle reimportazioni.