> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattone.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Reconciliation: payout Stripe automatici

> Come il tool legge da solo i payout Stripe dello studente, da quale chiave, con quali permessi, e cosa fare quando la prova dice che manca qualcosa.

> [!NOTE]
>
> **Stato al 24/10/2026**: attivo in produzione (tool Reconciliation PR #34, #35, #39, #40; piattaforma PR #449), per Cosmica e per gli studenti con Stripe collegato. Il CSV dall'Import mensile resta solo per i casi qui sotto che la lettura automatica non copre.

Con Stripe collegato il tool legge ogni notte alle 5 i **payout pagati** degli ultimi 10 giorni e scrive una riga per ogni incasso, uguale al CSV che prima si scaricava a mano. Un payout già presente (da CSV o da una lettura precedente) non si rilegge. Il periodo chiuso non si tocca mai.

## Da dove prende la chiave

In quest'ordine, la prima che trova vince:

1. **La chiave collegata nel tool**: Impostazioni → **Collega Stripe**. Serve a chi vuole una chiave solo per la riconciliazione, o a chi ha più account sotto un'organizzazione Stripe.
2. **La configurazione del server**, solo per Cosmica, finché non passa alla pagina.
3. **La chiave già collegata nella Mattone Platform** (Connessioni → Stripe). È il caso normale: lo studente l'ha già inserita per Conduit e per il sito, il tool la chiede alla piattaforma con una firma fra servizi, come per KrossBooking. Lo studente **non inserisce nulla** nel tool.

Nel tool la chiave è cifrata e non torna mai indietro: la pagina mostra solo l'inizio e le ultime quattro lettere (`rk_live_…AbCd`).

## Una chiave per tre usi

La chiave Stripe dello studente in piattaforma serve a link di pagamento in chat (Conduit), incassi del sito di prenotazione diretta e riconciliazione. Deve avere tutti i permessi dei tre usi: vedi [Stripe: pagamenti dello studente](https://docs.mattone.co/integrazioni/stripe/panoramica.md#permessi-della-chiave).

Per la sola riconciliazione bastano, in **Lettura**: **Balance**, **Balance Transaction Sources**, **Charges and Refunds**, **Payouts**. Charges serve davvero: dal pagamento si legge il nome del cliente, che abbina il payout alla prenotazione.

## La prova

Quando lo studente incolla una chiave, o clicca **Prova di nuovo**, il tool fa solo letture e risponde in chiaro:

| Messaggio | Cosa fare |
| - | - |
| «Collegamento riuscito» | Niente: da stanotte i payout entrano da soli. |
| «Manca la Lettura su: …» | In Stripe aprire la chiave limitata, mettere Lettura sulle voci elencate, salvare e riprovare. La chiave non si salva finché la prova non passa. |
| «Stripe non riconosce questa chiave» | Copiata male, revocata o scaduta: crearne una nuova. |
| «Manca l'ID account» | Incollare l'ID account (`acct_…`, in Stripe → Impostazioni → Dettagli account). Serve al numero delle fatture commissioni. |
| «È una chiave di TEST» | Funziona, ma i payout veri si leggono solo con una chiave `rk_live_`. |

## Numero fattura commissioni

Ultimi 8 caratteri dell'ID account in maiuscolo, poi `-AAAA-MM` (es. account `acct_1PLjEEFqhgkdJAR1`, settembre → `HGKDJAR1-2026-09`). È il formato delle fatture commissioni di Stripe, verificato sulle fatture vere di Cosmica.

## Più account sotto un'organizzazione

Chi ha più account Stripe sotto una sola organizzazione (Cosmica ne ha 39) crea **una** chiave dell'organizzazione (inizia con `sk_org_live_`):

* scheda **«Organizzazione»** → **Core**: **Lettura** sulle quattro voci;
* scheda **«Account connessi»**: niente. Sono gli account Connect, qui non servono. Con i permessi solo lì Stripe risponde «permesso mancante» su Payouts, Balance e Charges (verificato in produzione il 24/10/2026).

Nella pagina sceglie «Ho più account sotto un'organizzazione» e incolla gli ID degli account da leggere.

Due casi che la chiave dell'organizzazione non copre:

* **Account Connect di un'altra piattaforma** (a Cosmica: Milano - Torre): Stripe non lo fa leggere con la chiave dell'organizzazione. Serve una chiave limitata creata dentro quell'account, con gli stessi quattro permessi.
* **Payout di addebito automatico** (Stripe preleva dal conto invece di versare, a Cosmica: Milano - Vivaio): non è un incasso, il tool lo salta e prosegue con gli altri.

## L'account Stripe si crea da Stripe, mai da Kross

Quando si apre un appartamento nuovo, l'account Stripe va creato **dal dashboard Stripe dello studente** (o dalla sua organizzazione) e **poi** collegato a KrossBooking. Se invece lo si crea dal passaggio «crea account Stripe» dentro Kross, l'account nasce sotto la piattaforma Kross: non appartiene allo studente e il tool non riesce a leggerlo (messaggio «account Connect di una piattaforma esterna»). È successo a Cosmica con Milano - Torre. Per sistemare: rifare l'account da Stripe e ricollegarlo a Kross.

## Un account, una sola azienda

Lo stesso account Stripe (`acct_…`) non può essere letto da due tenant: il primo che lo usa ne diventa il proprietario, l'altro lo trova saltato con il motivo «già collegato a un'altra azienda». Se è giusto spostarlo, lo fa il team Mattone.

## Se non arriva niente

* La pagina dice «non collegato»: lo studente non ha Stripe né nel tool né in piattaforma.
* Un errore nella lettura notturna arriva come avviso Slack con il numero del tenant e l'account.
* Un payout la cui somma delle righe non torna con il bonifico (rimborsi, rettifiche) si importa lo stesso e si guarda a mano in riconciliazione.

## «Connetti con Stripe» (valutato, non fatto)

Un bottone che collega Stripe senza creare chiavi richiede una Stripe App pubblicata: revisione di Stripe (circa 4 giorni lavorativi, da rifare a ogni modifica), oppure al massimo 25 account in prova. Per ora si resta sulla chiave limitata.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.