Passa al contenuto principale

FSP Standard

Nella modalità standard, il prodotto FSP funziona in combinazione con i prodotti transazionali di Fabrick, come PSD2 Pay by Bank o Fabrick Orchestra. In questa pagina descriveremo come gestire il processo tramite API.

Creazione di una richiesta di dynamic cashout​

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.

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.

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 al seguente link:

  • Verification Payee Scheme Rulebook

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.

Callback​

La comunicazione asincrona da FSP verso i sistemi backend dei chiamanti avviene tramite due callback:

  • validationCallback
  • resultCallback

La callback viene eseguita in modalità fire-and-forget. Ciò significa che il sistema non si aspetta né elabora alcuna risposta dall'endpoint della callback. La responsabilità della gestione dei dati della callback ricade interamente sul sistema ricevente.

ValidationCallback​

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.

ResultCallback​

Viene invocata da FSP per notificare al consumer l'esito delle operazioni di dynamic cashout inviate. 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.