Passa al contenuto principale

VoP Responding

Descrizione​

Questo documento descrive le specifiche tecniche da implementare riguardanti il prodotto VoP Responding. Sono quindi indicate le linee guide e le informazioni che dovranno essere esposte verso Fabrick in modo che sia possibile, per l'istituto finanziario, rispondere in tempo reale alle richieste di verifica dell’intestatario di un conto ricevute da altri Payment Service Provider (PSP) o soggetti autorizzati.

Request​

Il PSP ricevente dovrà esporre un endpoint a propria scelta in modo che Fabrick possa richiamare l'API di verifica VoP tramite il modello riportato di seguito:

{
    "ownerName": "Mario Rossi",
    "type": "NAME",
    "iban": "DE02100100109307118603",
    "respondingBic": "ABCDBEBBXXX",
    "requesterBic": "XYZWDEFFYYY"
}

dove:

  • owner: Indica il nome dell’intestatario

  • type: indica il tipo di identificativo associato all'intestatario.

    • NAME- nome e cognome o ragione sociale

    • INACNO – Supporto per informazioni aggiuntive sul numero di conto di pagamento

    • VERLEI – Supporto per il codice VERLEI (Legal Entity Identifier) per identificare la controparte del pagamento

    • VERBIC – Supporto per anyBIC per identificare la controparte del pagamento

    • VCBANK – Supporto per il codice identificativo della banca della controparte del pagamento

    • VCCBID – Supporto per il codice identificativo CBID della controparte del pagamento

    • VCCHID – Supporto per il codice identificativo CHID della controparte del pagamento

    • VCCINC – Supporto per il codice identificativo CINC della controparte del pagamento

    • VCCOID – Supporto per il codice identificativo COID della controparte del pagamento

    • VCCUST – Supporto per il codice identificativo CUST della controparte del pagamento

    • VCDUNS – Supporto per il codice identificativo DUNS (Dun & Bradstreet) della controparte del pagamento

    • VCEMPL – Supporto per il codice identificativo EMPL della controparte del pagamento

    • VCGS1G – Supporto per il codice identificativo GS1G della controparte del pagamento

    • VCSREN – Supporto per il codice identificativo SREN della controparte del pagamento

    • VCSRET – Supporto per il codice identificativo SRET della controparte del pagamento

    • VCTXID – Supporto per il codice identificativo TXID della controparte del pagamento

    • VCBDID – Supporto per il codice identificativo BDID della controparte del pagamento

    • VCBOID – Supporto per il codice identificativo BOID della controparte del pagamento

    • VCPROP – Supporto per un codice proprietario per identificare la controparte del pagamento

  • iban: IBAN da verificare

  • respondingBic: BIC della banca rispondente.

  • requesterBic: BIC della banca richiedente

Il valore del parametro owner sarà indicato dalla tipologia type, ad esemprio invece dei dati anagrafici di una persona fisica potrebbe essere indicata la partita IVA di un'azienda:

{
    "owner": "22333244434343",
    "type": "VERLEI",
    "iban": "DE02100100109307118603",
    "respondingBic": "ABCDBEBBXXX",
    "requesterBic": "XYZWDEFFYYY"
}

Headers​

Il PSP dovrà prevedere anche i seguenti due headers:

X-Request-ID: {GUID}
X-Request-Timestamp: {Timestamp ISO 8601}
  • X-Request-ID: GUID della richiesta di VOP. È un identificativo univoco (GUID) associato alla richiesta VOP e viene generato dal chiamante per tracciare e identificare in modo preciso la transazione all'interno del sistema.
  • X-RequestDateTime: timestamp della richiesta VOP. Questo campo è soggetto a verifica di coerenza: la data deve corrispondere al giorno corrente e l'orario deve essere coerente con il momento dell'invio della richiesta. In caso contrario, la chiamata verrà rifiutata.

Tutti gli header utilizzati nelle richieste saranno codificati in UTF-8 per garantire la corretta interpretazione dei caratteri speciali e la compatibilità con il sistema.

Response​

Il PSP ricevente in risposta dovrà fornire tutti i dettagli per permettere a Fabrick di eseguire l'algortimo di match tra IBAN e intestatario e restituire l'esito finale al PSP richiedente. Le informazioni necessare dovranno essere esposte secondo il seguente modello:

{
    "status": "OK",
    "payload": {
        "iban": "IT51F0339512900052169783071",
        "resultId": "uniqueId",
        "result": "MTCH | CMTC | NMTC | NOAP",
        "matchedName": "Paolo Rossi",
        "resulDateTime": "2025-07-30T15:12:40.49668721+02:00",
        "accountHolder": "SINGLE | MULTIPLE | CORPORATION | ...",
        "list": [
            {
                "owner": "azienda srl",
                "ownerName": "Paolo",
                "ownerSurname": "Rossi",
                "type": "NAME | VERLEI | ...",
                "matchType": "MTCH",
                "matchedName": "Paolo Rossi"
            }
        ]
    }
}

dove:

  • iban: IBAN per il quale si vuole identificare l’owner. Parametro obbligatorio.

  • resultId: Identificativo associato alla richiesta di VOP, id univoco generato dal PSP rispondente. Parametro obbligatorio.

  • result: esito finale indicante il livello di corrispondenza. Parametro presente solamente in caso di proprio algoritmo del PSP ricevente (v. sezione successiva), in tal caso sarà obbligatorio. I possibili valori sono:

    • MTCH → Corrispondenza esatta (il nome fornito corrisponde esattamente a quello registrato).
    • CMTC → Corrispondenza parziale (il nome fornito è simile ma presenta differenze minime).
    • NMTC → Nessuna corrispondenza (il nome fornito non è presente nel sistema del PSP).
    • NOAP → Impossibilità di verifica (non è stato possibile effettuare la verifica per problemi tecnici).

  • matchedName presente e obbligatorio solo in caso di result pari a CMTC. Indica l'intestatario registrato nel sistema del PSP ricevente.

  • resulDateTime: data e ora di elaborazione della richiesta (formato ISO 8601). Parametro obbligatorio.

  • accountHolder: tipo di intestatario del conto, le possibilità saranno concordate con il PSP ricevente, alcuni esempi potrebbero essere SINGLE, MULTIPLE, CORPORATION. Parametro obbligatorio solo in caso di utilizzo algoritmo di match di Fabrick ((v. sezione successiva)

  • list: lista di intestatari collegati all'IBAN interessato. Generalmente sarà un solo elemento, ma potrebbe essere pari a due nel caso ad esempio di conti cointestati. Parametro obbligatorio solo in caso di utilizzo algoritmo di match di Fabrick ((v. sezione successiva). Ogni elemento della lista contiene i seguenti parametri:

    • owner: presente solamente in caso di persona giuridica. Indica il nome in base al valore del parametro type, type non può valere NAME.

    • *ownerName: presente sia in caso di persona giuridica che di persona fisica, type può valere solo NAME. Indica il nome dell’intestatario

    • *ownerSurname: presente solo in caso di persona fisica, quindi solo se type pari a NAME. Indica il cognome dell’intestatario

    • type: lo stesso parametro passato in fase di richiesta. Parametro obbligatorio.

    • matchType: deprecato. Sostituito dal parametro result

    • matchedName: deprecato. Sarà indicato solamente nella root dell'oggetto e non all'interno della lista

Algoritmo di match​

Fabrick ha implementato il proprio algoritmo di match i cui dettagli sono descritti nel documento dedicato. Il PSP ricevente ha la possibilità di:

  • lasciarlo inalterato

  • personalizzarne alcune regole tramite configurazioni concordate

  • sostituirlo con uno proprio.

Come indicato in precedenza, a seconda che si utilizzi l'algoritmo di Fabrick o il proprio il modello di riposta potrebbe variare. Di seguito alcuni esempi:

Algoritmo Fabrick - singolo intestatario

{
    "status": "OK",
    "payload": {
        "iban": "DE02100100109307118603",
        "resultId": "667676767",
        "resultDateTime": "2025-03-08T12:01:00Z",
        "accountHolder": "CORPORATION",
        "list": [
            {
                "owner": "22333244434343",
                "type": "VERLEI"
            }
        ]
    }
}

Algoritmo Fabrick - conto cointestato

{
    "status": "OK",
    "payload": {
        "iban": "DE02100100109307118603",
        "resultId": "667676767",
        "resultDateTime": "2025-03-08T12:01:00Z",
        "accountHolder": "MULTIPLE",
        "list": [
            {
                "ownerName": "Mario",
                "ownerSurname": "Rossi",
                "type": "NAME"
            },
            {
                "ownerName": "Giulia",
                "ownerSurname": "Di Stefano",
                "type": "NAME"
            }
        ]
    }
}

Mentre di seguito un esempio in cui il PSP ricevente scegliesse di applicare il proprio algoritmo. Il modello si sempificherebbe in quanto Fabrick non avrà necessità di avere informazioni relative all'intestatario, ma passerà semplcimente l'esito finale (result) restituito dal PSP. Di seguito un esempio con solo i parametri obbligatori:

{
    "status": "OK",
    "payload": {
        "iban": "IT51F0339512900052169783071",
        "resultId": "1234-5678",
        "result": "CMTC",
        "matchedName": "Paolo Rossi",
        "resulDateTime": "2025-07-30T15:12:40.49668721+02:00"
    }
}