Payout e riconciliazione

Quando un cliente paga tramite FlowAlp Pay, il denaro non arriva subito sul tuo conto bancario: viene prima raccolto nel tuo saldo FlowAlp Pay e poi trasferito con un payout. Questa guida spiega come funziona la liquidazione, che cosa contiene un payout e come riconciliare i payout con i tuoi ordini e l'estratto conto — manualmente dalla dashboard o in modo automatico tramite API.

Come vengono liquidati gli incassi#

Ogni pagamento confermato aumenta il tuo saldo dell'importo della transazione meno la commissione. Al momento del versamento, FlowAlp Pay raggruppa l'attività accumulata in un unico payout consolidato e lo trasferisce sul conto bancario (IBAN) configurato per il tuo account. Un payout copre quindi in genere molte transazioni più le relative commissioni e riporta un testo statement che compare sull'estratto conto, una date di versamento, una currency e i dati del conto di destinazione (destination) — tutto ciò che serve per abbinare l'accredito bancario.

Il ciclo di vita del payout#

Che cosa contiene un payout#

All'interno di un payout trovi un elenco di transfer. La maggior parte delle voci è di tipo transaction: contengono l'importo lordo del pagamento e la commissione trattenuta come item separati, oltre allo uuid e al reference_id della transazione (il tuo numero d'ordine). Gli altri tipi di transfer coprono commissioni di versamento, rettifiche, contestazioni e riserve. Tutti gli importi sono in unità minori e gli item di un transfer sommano sempre al suo importo netto — un pagamento di CHF 300.00 con CHF 3.00 di commissione compare come 30000 e -300, contribuendo al payout con 29700.

Riconciliare i payout con la contabilità#

1. Elenca i payout del periodo con la Payouts API e individua il payout che corrisponde all'accredito bancario (stessa data, stesso importo e stesso testo statement).
2. Carica i suoi transfer pagina per pagina con l'endpoint dei dettagli — è consigliata una dimensione di pagina di 100 voci.
3. Abbina ogni transfer di tipo transaction a un ordine nel tuo sistema usando reference_id o lo uuid della transazione.
4. Registra separatamente le voci di commissione (transaction-fee, payout-fee), così ricavi lordi e costi restano distinguibili.
5. Verifica che la somma di tutti i transfer corrisponda all'amount del payout e all'importo accreditato dalla banca.

Il collegamento funziona anche in direzione opposta: ogni transazione liquidata espone un payoutUuid, quindi puoi partire da un ordine e risalire al payout che l'ha contenuta — vedi Elencare e recuperare le Transaction. Per i controlli manuali, la dashboard FlowAlp Pay su https://pay.flowalp.com mostra gli stessi dati dei payout.

curl "https://api.pay.flowalp.com/v1.16/Payout/C6B438B9/details?instance=<tenant>&limit=100&offset=0" \
  -H "x-api-key: <api-secret>"

Automatizzare il monitoraggio dei payout#

Invece di fare polling, lascia che sia FlowAlp Pay ad avvisarti: le notifiche webhook vengono inviate quando un payout raggiunge gli stati processing, sent o failed (nessuna notifica per initiated, pending o under-review). È il trigger più semplice per avviare una riconciliazione automatica — vedi Configurare i webhook.