Financial Split Payments

Visualizza come Markdown

Introduzione

Financial Split Payments (FSP) è un prodotto che consente la raccolta dei flussi di pagamento in entrata provenienti da diversi gateway, generati tramite metodi di pagamento alternativi, carte o transazioni account-to-account, al fine di accreditarli tramite un unico flusso di payout ai merchant e a tutti gli altri soggetti coinvolti nel processo di business del cliente (aggregatori, intermediari, piattaforme, ecc.).

FSP può essere integrato con i prodotti di pagamento Fabrick oppure può essere utilizzato in modalità standaone. Di seguito una breve tabella che riassume le modlaità che saranno descritte nel dettaglio:

Tipo di Integrazione	Modalità	API Coinvolte	Quando usarlo
In combinazione con Fabrick	Statica	API Fabrick pisp	Se si usano già prodotti Fabrick e non serve lo split dinamico.
In combinazione con Fabrick	Dinamica	API Fabrick pisp + API FSP (split)	Se si usano già prodotti Fabrick e serve lo split dinamico.
Standalone	Statica	API Money-IN	Per un'integrazione indipendente da altri prodotti Fabrick.
Standalone	Dinamica	API Money-IN + API FSP (split)	Per un'integrazione indipendente con gestione dello split dinamico.

Nella modalità statica la percentuale di split dell'importo verso i vari conti viene definita in fase contrattuale e quindi non sarà necessario sviluppare ulteriori API. La percentuale di split sarà squndi sempre la medesima per ogni pagamento che dovrà essere gestito con lo split

L'approccio dinamico invece permette di decidere la percentuale di split tramite API per ogni sngolo importo ricevuto sul conto. Quindi: per ogni flusso di pagamento in entrata, il merchant seleziona le quote di allocazione tra gli stakeholder;

FSP esegue i processi di split in modo asincrono rispetto alle richieste e aggiorna i sistemi backend del merchant sullo stato di tali processi tramite callback.

Per quanto riguarda il tipo di integrazione invece sono possibilie due tipologie:

• in combinazione con i prodotti transazionali di Fabrick: come PSD2 Pay by Bank o Fabrick Orchestra con più metodi di pagamento alternativi, che notificano automaticamente a FSP l'accredito atteso (Money In) da validare.

• in modalità standalone: in questo caso, è responsabilità dell'aggregatore comunicare gli attributi del Money-In e specificare l'allocazione delle relative quote tra i vari client.

Qui è disponibile una semplice panoramica.

Glossario

FSP Sistema tecnico alla base del prodotto Financial Split Payments.

Aggregatore Soggetto giuridico che aggrega uno o più client.

Client Entità che riceve la propria quota allocata di crediti da uno specifico Money In attraverso un'operazione di split payment di primo livello. Un client può avere più contratti in relazione a diversi aggregatori.

Money In Credito ricevuto sul conto dell'aggregatore. Ogni Money In viene tipicamente suddiviso tra i client dell'aggregatore in base alle rispettive quote.

Money Out La porzione di fondi allocata a un client. I Money Out vengono elaborati tramite il flusso di cashout. Questo concetto corrisponde al "Cash In" nel contratto Financial Split Payments. All'interno di FSP, è l'entità tecnica utilizzata per attivare la distribuzione dei fondi, ovvero il cashout, in base alle regole di split, alle commissioni applicate e alle allocazioni residue.

Cash Out Uno split payment di secondo livello in cui ogni Money Out viene allocato a uno o più beneficiari.

CashoutOrders Definiscono come l'importo di un singolo moneyOut viene distribuito attraverso un'operazione di cashout. Ogni richiesta di Dynamic Cashout include uno o più Cashout Order, ciascuno dei quali specifica le regole per la suddivisione del moneyOut.

Split Payment Rules Una split rule è una parte di un Cashout Order che definisce una singola operazione di cashout. Specifica l'importo da trasferire a uno specifico beneficiary, determinando di fatto come viene distribuito il moneyOut complessivo.

Dynamic Cashout Un processo che definisce uno o più cashoutOrders, ciascuno dei quali specifica le regole di split per la distribuzione dell'importo di un moneyOut tra uno o più beneficiari.

Net Residual L'importo residuo dopo che tutti i cashout sono stati definiti e le commissioni applicabili dedotte. Questo residuo viene assegnato a un terzo soggetto—tipicamente il cliente—specificato nella definizione dei cashoutOrders.

Guida all'Integrazione: in combinazione con Fabrick

In questa modalità FSP funziona in combinazione con i prodotti transazionali di Fabrick, come PSD2 Pay by Bank o Fabrick Orchestra. Questo semplifica il processo in quanto tutte le informazioni relative al pagamento sono già implicitamente note a Fabrick .Infatti per ogni pagamento eseguito con uno dei prodotti Fabrick, FSP sarà già in attesa dell'accredito conoscendo in anticipo i relativi dettagli.

Modalità statica

In questo caso non è necessario alcuno sviluppo FSP in quanto le regole di split saranno stabilite infase di setup e sarnno valide ed applicate per tutti gli accrediti.

Sarà sufficiente sviluppare le API di inizialiazzazione di pagamento con il prodotto Fabrick prescelto.

Modalità dinamica

In questo seconda caso invece sarà necessario integrare il servizio API per applicare le regole di split per ogni accredito.

Il primo passo per creare una richiesta di dynamic cashout consiste nell'invocare il servizio Moneyout list. Vedere il servizio GET MoneyOutList. L'output di questo servizio fornisce l'elenco dei moneyOut disponibili per il cashout. Un esempio della risposta del servizio è il seguente:

{
  "status": "OK",
  "errors": [],
  "payload": [
    {
      "moneyOutCode": "MO2025101510000000001156",
      "amount": 100.00,
      "currency": "EUR",
      "moneyInSender": "SenderName",
      "moneyInTransferId": "EA24020312345678912345678912IT",
      "moneyInDescription": "AXYD302"
    }
  ]
}

Il secondo passo per creare una richiesta di dynamic cashout prevede l'invocazione del servizio POST CreateDynamicCashout. Questo servizio consente l'esecuzione delle transazioni di cashout per gli importi moneyOut specificati, facilitando la distribuzione dei fondi secondo le regole di split definite. Il servizio opera in modo asincrono. La risposta conferma se la richiesta è stata accettata per l'elaborazione oppure, in caso di errori di validazione del payload in ingresso, restituisce i problemi rilevati. L'esito di qualsiasi elaborazione accettata viene comunicato al chiamante tramite callback. Per ogni moneyOut specificato in un cashoutOrder, devono essere definite le split payment rules, indicando gli importi da allocare ai beneficiari designati. Di seguito un esempio dell'input del servizio. Qui viene definito un cashoutOrder che include due split rule. Inoltre, vengono specificati il netResidual, l'identificativo della chiamata e i riferimenti, in modo che FSP possa eseguire la callback per notificare lo stato del processo di cashout.

{
  "validationCallbackUri": "https://merchant.com/validation",
  "resultCallbackUri": "https://merchant.com/validation",
  "requestId": "a089a4bc-96df-48e2-92ba-9941aa718088",
  "cashOutOrders": [
    {
      "moneyOutCode": "MO122549191289212ANVZ000528",
      "splitRules": [
        {
          "amount": 10.93,
          "beneficiary": {
            "accountName": "Example",
            "paymentMethod": {
              "iban": "IT92V0326803202677155639978",
              "type": "SCT",
              "whitelisted": true
            }
          }
        }
      ]
    }
  ],
  "netResidual": {
    "accountName": "MERCHANTCOMPANY SPA",
    "paymentMethod": {
      "iban": "IT60X0542811101000000123456",
      "type": "SCT",
      "whitelisted": true
    }
  }
}

Vincoli per l'esecuzione del dynamic cashout

Coerenza dello Split

Il cashout può essere eseguito solo se la somma di tutti gli importi assegnati ai beneficiari, sommata alle commissioni applicabili, corrisponde esattamente all'importo totale del moneyOut.

Beneficiari Distinti

Ogni split rule deve definire beneficiari univoci. Nessun beneficiario può comparire più di una volta all'interno della stessa regola.

Allocazione del Residuo

Un netResidual deve essere definito per accreditare qualsiasi importo residuo dopo l'applicazione delle split rule e la deduzione delle commissioni. Il netResidual non deve essere presente tra i beneficiari definiti nelle split rule.

Omogeneità della Valuta

La valuta del moneyOut, dei cashoutOrders e del netResidual deve essere la stessa.

Gestione dell'Esito

L'operazione di cashout si conclude con un esito positivo o negativo. In caso di fallimento, è responsabilità del chiamante inviare una nuova richiesta di cashout per il moneyOut interessato.

 

Callback di validazione

La comunicazione asincrona da FSP verso i sistemi backend dei chiamanti avviene tramite callback. La callback comunica l'esito della validazione sostanziale della richiesta di dynamic cashout. Il sistema verifica la disponibilità degli elementi moneyout inclusi nella richiesta e, se abilitato, esegue il controllo VOP quando vengono utilizzati metodi di pagamento di tipo SCT. Se l'esito della validazione è OK, il processo di cashout viene avviato e una successiva callback ne riporta l'esito. In caso di esito KO, vengono riportati gli errori di validazione e l'intera richiesta di cashout viene rifiutata. Gli elementi moneyout inclusi nella richiesta restano disponibili per future richieste di dynamic cashout. Un esito KO si verifica quando la richiesta di cashout non è sufficientemente finanziata, oppure quando i controlli VoP sono abilitati e almeno uno di essi fallisce. La callback viene eseguita tramite il metodo POST sull'endpoint specificato dal chiamante. L'invocazione del servizio non richiede autorizzazione. In caso di fallimento tecnico della chiamata, viene applicata una politica di retry per tentare la chiamata più volte.

Di seguito la struttura del messaggio di callback.

{
  "requestCorrelationId": "string",
  "requestDateTime": "string",
  "validationResult": "OK",
  "cashOutOrdersErrors": [
    {
      "moneyOutCode": "string",
      "errors": [
        {
          "errorCode": "string",
          "description": "string",
          "params": "string"
        }
      ]
    }
  ]
}

• requestCorrelationId: Correlation ID della chiamata di dynamic cashout.
• requestDateTime: Data e ora della richiesta. Formato ISO 8601: YYYY-MM-DDThh:mm:ss.sssZ.
• validationResult: Possibili esiti della validazione:
  • OK: validazione completata con successo;
  • KO: validazione fallita e processo di cashout interrotto.
• cashOutOrdersErrors: CashoutOrders con errori.
• moneyOutCode: ID del moneyout non elaborabile.
• errors: Rappresenta qualsiasi errore che si verifica durante il ciclo di vita di una richiesta, inclusi sia i fallimenti di validazione sia i problemi di esecuzione:
  • errorCode: codice errore;
  • description: descrizione dell'errore;
  • params: descrizioni aggiuntive dell'errore.

Guida all'Integrazione: standalone

Nella modalità standalone è responsabilità dell'aggregatore comunicare gli attributi del Money-In e specificare l'allocazione delle relative quote tra i vari client. Per questo motivo sarà necessario integrare il seguente servizio API per condividere le informazioni del pagamento con FSP.

Modalità statica / dinamica

Per quanto riguarda la distinzione tra modalità statica o dinamica nulla cambia rispetto l'integrazione con i prodotti Fabrick, hanno sempre lo stesso significato. Di seguito descriveremo quindi l'endpoint in questione.

Creazione della richiesta di money-in

Il servizio POST CreateMoney-in consente all'aggregatore di comunicare a FSP un accredito atteso, ovvero i dati necessari per verificare i movimenti sul conto dell'aggregatore. Di seguito un esempio di utilizzo di questo servizio:

Esempio di input:

I dettagli dei campi inclusi nella richiesta sono spiegati nella documentazione tecnica del servizio.

Di seguito alcune note sull'utilizzo del servizio:

• Le valute utilizzate devono essere tra quelle supportate da FSP.
• Tutti gli importi nella richiesta CreateMoney-in devono utilizzare la stessa valuta.
• FSP non supporta la conversione valutaria.
• L'attributo reconciliationCallbackUri, se fornito dal chiamante, consente a FSP di inviare una callback al sistema del client per notificare l'esito della riconciliazione contabile.
• Il servizio può restituire come esito OK o KO.
• OK significa che il processo di riconciliazione è stato preso in carico; se ha esito positivo, FSP avvia il Cashin e il Cashout come specificato nel contratto con i client.
• I client sono identificati tramite la propria Partita IVA.
• Sono ammessi solo identificativi di client attivi nel dominio dell'aggregatore.
• I clientId non devono essere ripetuti all'interno della richiesta.
• La richiesta createMoney-in è identificata dal campo creditTransferId.
• Il valore di creditTransferId può essere riutilizzato solo dopo che la richiesta precedente ha completato la riconciliazione con esito KO.

Processo di riconciliazione FSP

Una volta acquisiti i dati dell'accredito atteso, FSP esamina gli accrediti osservati ricevuti sul conto dell'aggregatore. La riconciliazione viene eseguita tra un accredito atteso e un accredito osservato che condividono lo stesso identificativo univoco, transferId. La riconciliazione verifica quindi che i due accrediti corrispondano secondo le seguenti regole:

• L'acquirer associato all'accredito atteso deve essere correttamente identificato e riconosciuto.
• Entrambi gli accrediti devono essere denominati nella stessa valuta.
• Gli importi dell'accredito atteso e di quello osservato devono essere identici.

Il processo di riconciliazione può avere tre esiti:

• OK: La riconciliazione è stata completata con successo.
• KO: Almeno una regola di riconciliazione è stata violata; in questo caso, la richiesta può essere reinviata con i dati corretti.
• IN_PROGRESS: La riconciliazione è ancora in corso, poiché non tutti i dati richiesti relativi agli accrediti sono ancora disponibili.

Quando la riconciliazione viene infine completata, l'esito viene automaticamente aggiornato a OK o KO.

Callback di riconciliazione

FSP può inviare una callback al chiamante per notificare l'esito del processo di riconciliazione. Ciò avviene se il campo reconciliationCallbackUri è stato fornito nella richiesta POST CreateMoney-in. La struttura del payload della callback è illustrata di seguito.

{
  "reconciliationOutcome": {
    "creditTransferId": "TRN/CRO",
    "reconciliationStatus": "OK||KO||IN_PROGRESS",
    "moneyIn": {
      "amount": {
        "value": 100,
        "currency": "EUR"
      }
    },
    "observedTransfer": {
      "amount": {
        "value": 100,
        "currency": "EUR"
      }
    }
  }
}

La tabella seguente descrive la struttura del payload della callback.

Campo	Tipo	Obbligatorio	Utilizzo
reconciliationOutcome	Object	Y	Contenitore dei dati di risposta.
reconciliationOutcome.creditTransferId	String	Y	Identificativo del bonifico bancario, TRN/CRO, condiviso dall'accredito atteso e da quello osservato.
reconciliationOutcome.reconciliationStatus	Enum: OK, KO, IN_PROGRESS	Y	Stato della riconciliazione.
reconciliationOutcome.moneyIn	Object	Y	Dettagli dell'importo.
reconciliationOutcome.moneyIn.amount	Object	Y	Importo dell'accredito.
reconciliationOutcome.moneyIn.amount.value	Number, due decimali	Y	Tracciamento del ciclo di vita del conto.
reconciliationOutcome.moneyIn.amount.currency	String ISO 4212	Y	Codice valuta, 3 caratteri.
reconciliationOutcome.observedTransfer	Object	Y	Descrizione dell'accredito osservato.
reconciliationOutcome.observedTransfer.amount	Object	N	Dettagli dell'importo, se disponibili.
reconciliationOutcome.observedTransfer.amount.value	Number, due decimali	N	Dettagli dell'importo, se disponibili.
reconciliationOutcome.observedTransfer.amount.currency	String ISO 4212	N	Codice valuta, se disponibile.

Lo stato IN_PROGRESS viene riportato dalla callback quando la riconciliazione non è stata completata entro la soglia temporale definita.

Aspetti tecnici relativi all'invocazione della callback

La callback viene inviata utilizzando il metodo POST all'endpoint specificato nella richiesta POST CreateMoneyIn. In caso di fallimento dell'invocazione, FSP applica le proprie politiche di retry. La callback viene invocata senza alcun meccanismo di autorizzazione; tuttavia, Fabrick può fornire l'elenco degli indirizzi IP da inserire in whitelist.

ResultCallback

Viene invocata da FSP per notificare al consumer l'esito delle operazioni.

Ad oggi è disponibile solamente per la modalità dinamica e tipologia di integrazione con prodotti Fabrick.

La callback viene eseguita tramite il metodo POST sull'endpoint specificato dal chiamante. L'invocazione del servizio non richiede autorizzazione. In caso di fallimento tecnico della chiamata, viene applicata una politica di retry per tentare la chiamata più volte.

Il seguente esempio mostra la struttura del contenuto della callback.

{
  "requestCorrelationId": "string",
  "requestDateTime": "string",
  "completionDateTime": "string",
  "cashOutOrdersResults": [
    {
      "moneyOutCode": "string",
      "cashOutCode": "string",
      "cashOutAmount": 0,
      "currency": "string",
      "outcome": "OK",
      "error": {
        "errorCode": "string",
        "description": "string",
        "params": "string"
      },
      "transfer": {
        "amount": 0,
        "currency": "string",
        "accountName": "string",
        "paymentMethod": {
          "transferId": "string",
          "iban": "string",
          "whitelisted": true,
          "countryISOCode": "string",
          "address": "string",
          "swiftCode": "string",
          "accountNumber": "string",
          "city": "string",
          "type": "SCT"
        }
      }
    }
  ]
}

• requestCorrelationId: Correlation ID della chiamata di dynamic cashout.
• requestDateTime: Data e ora della richiesta. Formato ISO 8601: YYYY-MM-DDThh:mm:ss.sssZ.
• completionDateTime: Data e ora che indicano quando l'elaborazione della richiesta è stata completata. Formato ISO 8601: YYYY-MM-DDThh:mm:ss.sssZ.
• cashOutOrdersResults: rappresenta un cashout order elaborato. Se il cashout è stato eseguito con successo, la risposta include i dettagli del bonifico bancario associato. Se l'esecuzione è fallita, le informazioni sul trasferimento vengono omesse e vengono forniti i dettagli dell'errore.
• moneyOutCode: identificativo del moneyout associato al cashout.
• cashOutCode: identificativo del cashout generato dal sistema.
• cashOutAmount: importo del cashout espresso con due cifre decimali.
• currency: valuta del cashout. Formato 3 caratteri ISO 4217.
• outcome: Possibili esiti della validazione:
  • OK: validazione completata con successo;
  • KO: validazione fallita e processo di cashout interrotto.
• error: sezione valorizzata in caso di esito KO:
  • errorCode: codice errore;
  • description: descrizione dell'errore;
  • params: informazioni aggiuntive sull'errore.
• transfer: dettagli del bonifico bancario associato a questo cashout. Il trasferimento può essere condiviso tra più cashout. Questo campo è presente solo se il cashout è stato elaborato con successo.
• amount: importo del trasferimento.
• currency: valuta del trasferimento. ISO 4217.
• accountName: Nome completo del destinatario del bonifico bancario.
• paymentMethod: informazioni relative al metodo di pagamento da utilizzare per la transazione di split. Le opzioni supportate sono bonifico bancario SEPA e bonifico bancario internazionale. I bonifici SEPA sono indicati come SCT, mentre i bonifici internazionali sono indicati come WIRE.
• transferId: Identificativo del trasferimento. Quando il tipo è SCT, questo identificativo contiene il codice TRN oppure il codice CRO.
• iban: IBAN del beneficiario. Questo campo è obbligatorio quando il metodo di pagamento selezionato è SEPA (SCT).
• whitelisted: Il flag whitelisted indica se, nel caso del tipo di pagamento SCT, la coppia IBAN-beneficiario debba essere considerata attendibile e quindi esente dal controllo VoP. Non presente se il trasferimento è di tipo WIRE.
• countryISOCode: Codice paese del beneficiario espresso nel formato ISO 3166 a due caratteri. Presente se il tipo è WIRE.
• address: Indirizzo del beneficiario. Non deve essere fornito a meno che il tipo non sia WIRE; opzionale quando il tipo è WIRE.
• swiftCode: Codice SWIFT richiesto in caso di bonifico bancario internazionale (WIRE). Deve essere valorizzato se il tipo è WIRE.
• accountNumber: Numero di conto bancario richiesto per i trasferimenti internazionali. Deve essere valorizzato se il tipo è WIRE.
• city: Città di residenza del beneficiario. Richiesta quando il metodo di pagamento selezionato è il bonifico bancario internazionale. Non deve essere fornita a meno che il tipo non sia WIRE; opzionale quando il tipo è WIRE.
• type: Tipi di pagamento supportati: SCT per i bonifici SEPA, WIRE per i bonifici non SEPA.

Verification of Payee (VoP)

Il processo di Verification of Payee (VoP) si applica ai SEPA Credit Transfer ed è stato introdotto nell'ambito del Regolamento UE sui pagamenti istantanei (Instant Payments Regulation), in vigore dal 9 ottobre 2025.

Il VoP garantisce che l'IBAN fornito per un bonifico corrisponda al nome del beneficiario previsto, contribuendo a prevenire frodi e pagamenti erroneamente indirizzati.

Ovviamente questa sezione è utile per quanto riguarda la modalità dinamica, in quanto in caso di modalità statica i conti saranno controllati in fase di setup.

Esiti del controllo VoP:

• MATCH: Corrispondenza completa tra IBAN e nome del titolare del conto.
• CLOSE MATCH: Corrispondenza parziale. Codice errore: CMTC.
• NO MATCH: Nessuna corrispondenza. Codice errore: NMTC.
• NOT AVAILABLE: Il controllo VoP non è stato eseguibile dal PSP ricevente. Codice errore: NOAP.
• TECHNICAL ERROR: Errore interno del sistema. Codice errore: ERR.

Ulteriori informazioni sono disponibili nella sezione dedicata.

VoP nel processo di Cashout FSP

All'interno del framework Financial Split Payment, le operazioni di cashout vengono eseguite automaticamente in modalità unattended.

Durante l'onboarding, i merchant possono decidere se abilitare o meno i controlli VoP per le richieste di dynamic cashout:

• Se i controlli VoP sono disabilitati, il sistema salta la verifica per tutte le richieste di cashout;
• Se i controlli VoP sono abilitati, il sistema esegue il controllo durante la fase di validazione sostanziale della richiesta di cashout.

Comportamento del flag Whitelisted

Quando i controlli VoP sono abilitati, per gestire gli errori VoP è possibile utilizzare un flag di whitelist:

• whitelisted = TRUE: Forza il sistema a saltare la verifica VoP.
• whitelisted = FALSE e VoP checks abilitato: la verifica VoP è abilitata.
• whitelisted = FALSE e VoP checks disabilitato: la verifica VoP è disabilitata.
• Se il campo non è presente nel payload, si assume come valore predefinito FALSE.

Di seguito un tipico flusso di processo che coinvolge la verifica VoP:

• Una richiesta di dynamic cashout viene inviata senza il campo opzionale whitelisted.
• Se si verificano errori VoP, questi vengono restituiti nella callback di validazione.
• Il chiamante può quindi:
  • Correggere i dati del beneficiario e reinviare la richiesta, oppure
  • Reinviare la richiesta con gli stessi dati impostando whitelisted = TRUE per bypassare la verifica VoP.