Fabrick Verification Of Payee

Descrizione flusso e API

Fabrick offre una soluzione API per la Verification Payee che consente di verificare i dati di pagamento ovvero nome o codici identificativi e IBAN per una transazione di pagamento. L'API restituisce una risposta che indica se il nome del beneficiario corrisponde o meno con il nome registrato nel sistema di pagamento (PSP responding). Questa documentazione fornisce i dettagli per implementare l'API, con particolare attenzione alla distinzione tra persona fisica (Natural Person) e persona giuridica (Legal Person), e alla gestione delle richieste in modalità singola e bulk.

Il flusso di funzionamento dell'API è rappresentato nel diagramma di sequenza seguente:

Di seguito un esempio base dell'API

POST /v4.0/vop/verify

{
    "ownerName": "Mauro Rossi",
    "iban": "DE02100100109307118603"
}

Headers

Headers obbligatori

In aggiunta agli header Auth-Schema e Api-Key comuni per i prodotti Fabrick, il prodotto richiede i seguenti headers:

X-Request-Code: 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. Formato ISO 8601 esempio 2025-02-05T10:15:32.456Z
X-Operation-Code: codice univoco del bonifico o della transazione associata alla richiesta di VOP.

Codifica degli Header

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.

Request

Se il soggetto è una persona fisica (Natural Person) allora l'identificazione avviene tramite la combinazione ownerName + IBAN.
Se il soggetto è un'entità legale (Legal Entity) allora sarà possibile utilizzare la combinazione ownerName + IBAN oppure ownerIdentification + IBAN.

Richiesta per Persona Fisica (Natural Person)

La richiesta per una persona fisica include almeno il nome del beneficiario e l'IBAN del suo conto bancario. È opzionale fornire anche una descrizione del pagamento.

{
    "ownerName": "Mauro Rossi",
    "iban": "DE02100100109307118603",
    "description":"description Bonifico"
}

dove

la descrizione dei parametri dell'oggetto JSON che hai fornito:

ownerName: contiene il nome del beneficiario, che può essere una persona fisica o una persona giuridica (azienda). È un parametro obbligatorio per natural person. Esempio: "Fabrick SPA"(legal entity) o "Mauro Rossi" (Natural Person)
iban: è il valore dell'IBAN (International Bank Account Number) che identifica univocamente il conto bancario. Viene utilizzato per facilitare le transazioni internazionali e deve seguire un formato standard. *Esempio "DE02100100109307118603".
description: campo opzionale e fornisce una descrizione aggiuntiva sul conto utilizzato.

Richiesta per Persona Giuridica (Legal Entity)

In caso di persona giuridica si potrà scegliere la stessa modalità della persona fisica oppure la combinazione ownerIdentification + IBAN. Di seguito un esempio

{
    "iban": "DE02100100109307118603",
    "ownerName": "Azienda Spa"
    "description": "description Bonifico", //opzionale
    "ownerIdentification": {
        "value": "549300DTUYXVMJXZNY75",
        "type": "VERLEI",
        "nameProprietary":""
    }
}

L'oggetto ownerIdentification contiene il codice di identificazione univoco assegnato a un'entità legale e il tipo di identificatore utilizzato. Questo serve a verificare l'entità legale associata all'IBAN.

value: Il codice di identificazione effettivo dell'entità legale ad esempio, "549300DTUYXVMJXZNY75".
type : Il tipo di codice di identificazione. Di seguito l'elenco dei type supportati
- NAME: caso in cui nella richiesta sia presente il parametro ownerName
- 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 BANK 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. In questo caso sarà necessariospecificare il parametro nameProprietary inserendo il nome del codice proprietario.

Response

L'API restituirà una risposta che indica se c'è corrispondenza tra il nome del beneficiario e quello registrato nel sistema. Le possibili risposte sono le seguenti:

Risposta con Match Esatto (MTCH)
Risposta con Corrispondenza Parziale (CMTC)
Risposta con Nessuna Corrispondenza (NMTC)
Risposta con Impossibilità di Verifica (NOAP)

1. Risposta con Match Esatto (MTCH)

Il nome del beneficiario è esattamente corrispondente con quello registrato nel sistema del PSP.

-- Natural Person -- 
{
    "status": "OK",
    "payload": {
        "id": "7f8f3c4e-319f-4a3a-9d83-4e4c2cbfe9f2",
        "requestCode": "123e4567-e89b-12d3-a456-426614174000",
        "operationCode": "bonifico-537",
        "pspProcessingTimes":"300",
        "requestDateTime":"2025-02-05T10:15:32.456Z",
        "ownerName": "Mauro Rossi",
        "iban": "DE02100100109307118603",
        "description": "description Bonifico",
        "matchType": "MTCH"
    }
}

-- Legal Entity --
{
    "status": "OK",
    "payload": {
        "id": "3cb95c33-e2e3-4f94-b3ad-bab9a6141e9a",
        "requestCode": "123e4567-e89b-12d3-a456-426614174000",
        "operationCode": "bonifico-537",
        "pspProcessingTimes":"300",
        "requestDateTime": "2025-02-05T10:15:32.456Z",
        "ownerIdentification": {
            "value": "549300DTUYXVMJXZNY75",
            "type": "VERLEI" 
        },
        "iban": "DE02100100109307118603",
        "description": "description Bonifico",
        "matchType": "MTCH"
    }
}

2. Risposta con Corrispondenza Parziale (CMTC)

Il nome del beneficiario ha una corrispondenza parziale con il nome registrato nel sistema del PSP. Questo può accadere quando c'è una piccola differenza nel nome (es. errori di battitura).

-- Natural Person -- 
{
    "status": "OK",
    "payload": {
        "id": "d11fd2a9-2350-4c9b-a3d4-ea24c67084ab",
        "requestCode": "123e4567-e89b-12d3-a456-426614174000",
        "operationCode": "bonifico-537",
        "pspProcessingTimes":"300", //millisecondi
        "requestDateTime":"2025-02-05T10:15:32.456Z",
        "ownerName": "mauro Rosso",
        "iban": "DE02100100109307118603",
        "description": "description Bonifico",
        "matchType": "CMTC",
        "matchedName": "Mauro Rossi"
  }
}

-- Legal Entity --
{
    "status": "OK",
    "payload": {
        "id": "1fcb92d4-2f14-4e34-b2e3-dfc70d0fa89f",
        "requestCode": "123e4567-e89b-12d3-a456-426614174000",
        "operationCode": "bonifico-537",
        "pspProcessingTimes":"300", //millisecondi
        "requestDateTime": "2025-02-05T10:15:32.456Z",
        "ownerName": "Fabbrick SPA",
        "iban": "DE02100100109307118603",
        "description": "description Bonifico",
        "matchType": "CMTC",
        "matchedName": "Fabrick SPA"
    }
}

3. Risposta con Nessuna Corrispondenza (NMTC)

Non è stata trovata alcuna corrispondenza per il nome del beneficiario.

-- Natural Person -- 
{
    "status": "OK",
    "payload": {
        "id": "8bde1ce2-d591-4200-8fbd-926c9f5e1d90",
        "requestCode": "123e4567-e89b-12d3-a456-426614174000",
        "operationCode": "bonifico-537",
        "pspProcessingTimes":"300", //millisecondi
        "requestDateTime":"2025-02-05T10:15:32.456Z",
        "ownerName": "Mauro Rossi",
        "iban": "DE02100100109307118603",
        "description": "description Bonifico",
        "matchType": "NMTC"
  }
}
-- Legal Entity --
{
    "status": "OK",
    "payload": {
        "id": "23ef65d1-88d4-44ec-962a-301d1cb80e5c",
        "requestCode": "123e4567-e89b-12d3-a456-426614174000",
        "operationCode": "bonifico-537",
        "pspProcessingTimes":"300", //millisecondi
        "requestDateTime":"2025-02-05T10:15:32.456Z",
        "ownerIdentification": {
            "value": "549300DTUYXVMJXZNY75",
            "type": "VERLEI"
        },
        "iban": "DE02100100109307118603",
        "description": "description Bonifico",
        "matchType": "NMTC"
  }
}

4. Risposta con Impossibilità di Verifica (NOAP)

Non è stato possibile effettuare la verifica del nome del beneficiario per ragioni tecniche.

-- Natural Person -- 
{
    "status": "OK",
    "payload": {
        "id": "6b83b3f2-15fc-42c6-8bc4-d3995b36f34a",
        "requestCode": "123e4567-e89b-12d3-a456-426614174000",
        "operationCode": "bonifico-537",
        "pspProcessingTimes":"300", //millisecondi
        "requestDateTime":"2025-02-05T10:15:32.456Z",
        "ownerName": "Mauro Rossi",
        "iban": "DE02100100109307118603",
        "description": "description Bonifico",
        "matchType": "NOAP"
  }
}
-- Legal Entity --
{
    "status": "OK",
    "payload": {
        "id": "e2a3769c-7e5a-47c1-9fe7-74588e80e6c3",
        "requestCode": "123e4567-e89b-12d3-a456-426614174000",
        "operationCode": "bonifico-537",
        "pspProcessingTimes":"300", //millisecondi
        "requestDateTime":"2025-02-05T10:15:32.456Z",
        "ownerIdentification": {
            "value": "549300DTUYXVMJXZNY75",
            "type": "VERLEI"
        },
        "iban": "DE02100100109307118603",
        "description": "description Bonifico",
        "matchType": "NOAP"
  }
}

L'API restituisce una risposta in formato JSON in cui come si può notare l'informazione principale è quella di indicare se il nome del beneficiario fornito in richiesta corrisponde o meno a quello censito nel sistema del PSP. La risposta è composta da due sezioni principali: il campo status, che conferma l'elaborazione della richiesta, e il payload, che contiene tutte le informazioni dettagliate sulla verifica effettuata. Nel payload sono riportati anche i parametri di richiesta.

All'interno del payload sono presenti o seguenti parametri:

id: identificativo univoco assegnato da Fabrick alla singola richiesta di VOP (tipo valore uid). Esempio: "e2a3769c-7e5a-47c1-9fe7-74588e80e6c3"
requestCode: UID univoco della richiesta fornito dal chiamante negli header della richiesta. Serve per tracciare la richiesta in modo univoco (inserita negli header). Esempio: "123e4567-e89b-12d3-a456-426614174000"
operationCode: codice univoco della transazione associata alla richiesta di verifica del nome del beneficiario, fornito dal client negli header (inserita negli header). Esempio: "bonifico-537"
requestDateTime: data e ora fornite dal chiamante nella richiesta, che rappresentano il momento di invio della richiesta dal punto di vista del client (inserita negli header). Formato ISO 8601. Esempio: "2025-02-05T10:15:32.456Z"
pspProcessingTimes: tempo di elaborazione della richiesta da parte del responding PSP, espresso in millisecondi. Esempio: "300"
matchType: indica il tipo di corrispondenza tra il nome del beneficiario fornito e quello registrato nel sistema del PSP. Può assumere quattro valori:
- "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: rappresenta il nome corretto registrato nel sistema del PSP, restituito solo in caso di corrispondenza parziale (matchType CMTC).

Lista Types gestiti dal PSP

Come indicato sopra nel caso di persona giuridica è possibile richiedere la verifica VOP passando diverse tipologie di informazioni (parametro type) ed ogni PSP può decidere in autonomia quali esporre e gestire. Per sapere le differenti tipologie gestite Fabrick mette a disposizione il servizo GET getPspType

POST {{domain}}/v4.0/vop/owner-type

{
  "iban": "IT69T0326822300052545868410"
}

si otterrà in risposta la lista dei tipi esposti dal PSP come mostra il seguente esempio

{
  "status": "OK",
  "payload": {
    "iban": "IT69T0326822300052545868410",
    "supportedCodes": [
      "LEI",
      "BIC",
      "CBID",
      "VAT",
      "VCDUNS"
    ]
  }
}

Recuperare i dettagli di una richiesta VOP passata

Ricerca

Fabrick espone il servizio di ricerca che permette di recuperare tutte le rciheste di VOP eseguite in passato.

POST {{domain}}/v4.0/vop/verify/search

{
}

ottenendo così in risposta la lista completa

{
  "list": [
    {
      "id": "403d5945-cf71-4cc9-bce8-9c323e84eeae",
      "requestCode": "03a7c380-152f-4981-b87a-9241b58863ca",
      "operationCode": "VOP",
      "requestDateTime": "2025-07-08T07:47:21.041Z",
      "ownerName": "Paolo Verdi",
      "iban": "IT69T0326822300052545868410"
    },
    ...
    {
      "id": "081af3f6-ea7b-4d6b-9069-565820fec015",
      "requestCode": "15338105-0fb5-4362-a5ff-3afe539f80a6",
      "operationCode": "VOP",
      "requestDateTime": "2025-07-08T12:25:28.869Z",
      "ownerName": "Mario Rossi",
      "iban": "IT69T0326822300052545868410"
    }
  ]
}

E' ovviamente possibile per diversi parametri, tra cui:

requestCode (es: "c67984d3-8055-40d5-ae1b-3a0040fab9d1")
operationCode (es: anOpeCode)
fromRequestDateTime (es: "2025-07-07T15:19:17.225Z")
toRequestDateTime (es: "2025-07-07T15:19:17.225Z")
ownerName: ko
matchedName: (es. "Mauro Rossi")
ownerIdentification: mi mandi un esempio?
iban: (es: IT75Z0300203280000400162700)
description: ko
matchType (es: NMTC)

Dettagli tramite requesterId

In alternativa è possibile recuperare i dettagli di una richiesta VOP tramite il proprio id univoco grazie al servizio GET GetVopInfoById

{{domain}}/v4.0/vop/verify/{{requesterId}}

in risposta si otterrà un unico elemento con i dettagli della richiesta VOP

{
  "status": "OK",
  "payload": {
    "id": "4129eeeb-b111-475c-b71b-ad01ef9332cf",
    "requestCode": "d3f2ef1e-d0ee-4582-b5a4-5591a8df15f5",
    "operationCode": "anOpeCode",
    "pspProcessingTime": 216,
    "requestDateTime": "2025-07-08T15:18:12.442Z",
    "ownerName": "Mauro Rossi",
    "iban": "IT40S0542811101000000123456",
    "matchType": "MTCH"
  }
}

Modalità Bulk (solo per PSP)

L’API supporta la modalità bulk per effettuare verifiche multiple di IBAN in un’unica richiesta. Sono disponibili due modalità operative: sincrona e asincrona.

Entrambe le modalità prevedono lo stesso input, headers e body, ma cambia ovviamente il tipo di risposta. Nel caso sincrono sraanno restituiti tutti gli esisti direttamente nella response, nel caso asincrono verranno inviati tarmite notifica S2S.

Di seguito un esempio.

Header obbligatori

X-Bulk-Request-Code: GUID della richiesta di VOP. È un identificativo univoco (GUID) associato alla richiestaVOP e viene generato dal chiamante per tracciare e identificare in modo preciso la transazione all'interno del sistema (guid univoco a richiesta).
X-Bulk-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.*Formato ISO 8601 esempio 2025-02-05T10:15:32.456Z
X-Bulk-Operation-Code: codice associato all'operazione bulk (che potrà essere utilizzato nelle ricerche). Questo verrà restituito anche nei singoli oggetti di risposta come operationCode.

Richiesta sincrona

POST {{domain}}/v4.0/vop/verify/bulk/sync

Richiesta asincrona

POST {{domain}}/v4.0/vop/verify/bulk

Body

{
  "list": [
    {
      "ownerName": "Mauro Rossi",
      "iban": "DE02100100109307118603",
      "description": "description Bonifico",
      "requestCode":"guid1"
    },
    {
      "iban": "DE02100100109307118777",
      "description": "description Bonifico",
      "ownerIdentification": {
        "value": "549300DTUYXVMJXZNY75",
        "type": "VERLEI"
      },
      "requestCode":"guid2"
    },
    {
      "ownerName": "Riccardo Olivetti",
      "iban": "DE02100100109307118555",
      "description": "description Bonifico",
      "requestCode":"guid3"
    },
    {
      "iban": "DE02100100109307118888",
      "description": "description Bonifico",
      "ownerIdentification": {
        "value": "5535353546211",
        "type": "VERLEI"
      },
      "requestCode":"guid4"
    }
  ]
}

Se il parametro requestCode viene inserito in uno degli oggetti della lista, allora dovrà essere presente in tutti gli elementi; in caso contrario verrà restituito l'errore Request not valid.

Verifica Bulk Sincrona

Nella modalità sincrona gli esiti saranno restituiti direttamente all'interno della response. Questa modalità è quindi consigliata quando il numero di richieste (elementi dell'oggetto list) è limitato per ovvie ragioni di ottimizzazione

Di seguito un esempio di risposta, come anticipato conterrà direttamente l'esito finale

{
    "status": "OK",
    "payload": {
        "bulkId": 23212,
        "bulkOperationCode": "bonifico-537",
        "bulkRequestCode": "123e4567-e89b-12d3-a456-426614174000",
        "bulkRequestDateTime": "2025-02-05T10:15:32.456Z",
        "list": [
            {
                "id": "a1c2cb45-8f4c-4dc7-a177-1a734232a4ed",
                "pspProcessingTimes": "300",
                "requestCode": "guid1",
                "operationCode": "bonifico-537",
                "requestDateTime": "2025-02-05T10:15:32.456Z",
                "ownerName": "Mauro Rossi",
                "iban": "DE02100100109307118603",
                "description": "description Bonifico",
                "matchType": "NMTC"
            }
        ]
    }
}

Dove:

bulkId identificativo univoco della richiesta bulk (globale). Utile per il tracciamento complessivo dell’elaborazione.
id: identificativo della singola richiesta di verifica VOP. Utile per eventuali chiamate ai servizi di dettaglio della singola verifica.

Questa modalità elabora immediatamente l’intera lista e restituisce il risultato nella stessa risposta. È ideale per volumi contenuti. Di seguito un altro esempio contenente la risposta a 4 richieste VOP, come si può notare vengono suddivisi i casi di OK dai casi di KO.

{
    "status": "OK",
    "payload": {
        "bulkId": 23212,
        "bulkOperationCode": "bonifico-537",
        "bulkRequestCode": "123e4567-e89b-12d3-a456-426614174000",
        "bulkRequestDateTime": "2025-02-05T10:15:32.456Z",
        "list": [
            {
                "id": "a1c2cb45-8f4c-4dc7-a177-1a734232a4ed",
                "pspProcessingTimes": "300",
                "requestCode": "guid1",
                "operationCode": "bonifico-537",
                "requestDateTime": "2025-02-05T10:15:32.456Z",
                "ownerName": "Mauro Rossi",
                "iban": "DE02100100109307118603",
                "description": "description Bonifico",
                "matchType": "NMTC"
            },
            {
                "id": "0c215a74-8b17-4bcf-9ae6-c6c1911d3e91",
                "pspProcessingTimes": "300",
                "requestCode": "guid2",
                "operationCode": "bonifico-537",
                "requestDateTime": "2025-02-05T10:15:32.456Z",
                "iban": "DE02100100109307118603",
                "description": "description Bonifico",
                "matchType": "NMTC",
                "matchedIdentification": {
                    "value": "549300DTUYXVMJXZNZ75",
                    "type": "VERLEI"
                }
            }
        ],
        "errors": [
            {
                "id": "7917266d-d6e2-46a3-968f-cdd30f8e3f30",
                "pspProcessingTimes": "300",
                "requestCode": "guid3",
                "operationCode": "bonifico-537",
                "requestDateTime": "2025-02-05T10:15:32.456Z",
                "ownerName": "Riccardo Olivetti",
                "iban": "DE02100100109307118555",
                "description": "description Bonifico",
                "errorCode": "VOP-001",
                "errorDescription": "EDS Not Found!"
            },
            {
                "id": "22e9c690-02a0-47fc-9e3f-087a3ea7e32c",
                "pspProcessingTimes": "300",
                "requestCode": "guid4",
                "operationCode": "bonifico-537",
                "requestDateTime": "2025-02-05T10:15:32.456Z",
                "iban": "DE02100100109307118888",
                "description": "description Bonifico",
                "ownerIdentification": {
                    "value": "5535353546211",
                    "type": "VERLEI"
                },
                "errorCode": "VOP-002",
                "errorDescription": "Connection Error!"
            }
        ]
    }
}

Verifica Bulk Asincrona

La verifica bulk asincrona consente l’invio di più richieste di verifica in un’unica chiamata avviando l’elaborazione in background. Questa modalità è particolarmente adatta a gestioni di distinte e consente una gestione efficiente delle richieste da parte del PSP.

In questo caso la risposta indicherà solamente una presa in carico e non restituirà nessun esito. La risposta non contiene ancora i risultati, ma solo un riferimento all’elaborazione in corso:

{
  "status": "OK",
  "payload": {
    "bulkId": 23212,
    "bulkOperationCode": "bonifico-537",
    "bulkRequestCode": "123e4567-e89b-12d3-a456-426614174000",
    "bulkRequestDateTime": "2025-02-05T10:15:32.456Z",
    "status": "PENDING"
  }
}

L’elaborazione della richiesta asincrona è gestita tramite un sistema a stati. Lo stato della richiesta può essere monitorato tramite due modalità:

Polling: il Requester potrà monitorare lo stato via l'API GET /vop/verify/bulk/{{bulkId123}}
Callback il Requester potrà esporre un endpoint e sarà Fabrick a fornire i vari esiti tramite notifica S2S

Di seguito tutti i valori che lo stato può assumere:

Stato	Descrizione
PENDING	La richiesta bulk è stata correttamente presa in carico ed è in elaborazione.
COMPLETED	Tutte le verifiche sono state completate con successo. La risposta di ogni PSP potrebbe essere positiva o negativa. Lo stato indica solamente che tutti i PSP responding hanno risposto correttamente senza alcun errore tecnico.
ERROR	Si è verificato almeno un errore durante l’elaborazione ovvero non tutte le richieste hanno ottenuto una risposta del PSP responding.

Polling

In questo caso sarà possibile recuperare gli esiti tramite due APIs: la prima, l'unica delle due ad essere getsita in polling, permette di recuperare lo stato relativo alla richiesta bulk, ovvero indicherà quando tutte le richieste sono state concluse.

Una volta ottenuto in risposta lo status completed sarà possibile invocare la seconda API per recuperare i dettagli e gli stati di tutte le richieste effettuate.

GET getBulkRequest

GET {{domain}}/v4.0/vop/verify/bulk/{{bulkId}}

restituirà lo stato a livello aggregato

{
  "status": "OK",
  "payload": {
    "bulkId": 23212,
    "bulkOperationCode": "bonifico-537",
    "bulkRequestCode": "123e4567-e89b-12d3-a456-426614174000",
    "bulkRequestDateTime": "2025-02-05T10:15:32.456Z",
    "status": "COMPLETED"
  }
}

Una volta conclusa la fase di polling si potranno ottenere i dettagli tramite l'API GET getBulkDetails

GET {{domain}}/v4.0/vop/verify/bulk/{{bulkId}}/details

In risposta si avrà lal ista di tutti gli elementi come mostra l'esempio:

{
  "status": "OK",
  "payload": {
    "bulkId": 23212,
    "bulkOperationCode": "bonifico-537",
    "bulkRequestCode": "123e4567-e89b-12d3-a456-426614174000",
    "bulkRequestDateTime": "2025-02-05T10:15:32.456Z",
    "status": "COMPLETED",
    "list": [
      // Lista elementi con risposta valida
    ]
  }
}

Come già noto potrebbero essere restituite due differenti liste, la prima contenente le richieste aventi una risposta valida e la seconda contenente le richieste andate in errore.

{
  "status": "OK",
  "payload": {
    "bulkId": 23212,
    "bulkOperationCode": "bonifico-537",
    "bulkRequestCode": "123e4567-e89b-12d3-a456-426614174000",
    "bulkRequestDateTime": "2025-02-05T10:15:32.456Z",
    "status": "ERROR",
    "list": [
      // Lista elementi con risposta valida
    ],
    "errors": [
      // Lista elementi in errore
    ]
  }
}

I parametri bulkId e id hanno lo stesso significato descritto precedentemente.

Notificaton S2S

In questo caso sarà possibile evitare il polling in quanto sarà Fabrick ad inviare una notifica S2S ad un endpoint prescelto una volta conclusa la verifica bulk.

Questa è la scelta consigliata

Per tuttii i dettagli su questa modalità fare riferimento al documento specifico "Notifiche S2S"

Gestione degli errori

In questa sezione vengono indicati tutti i codici di errore restituti. Gli errori includono un codice identificativo (code) e una descrizione (description).

Descrizione Errore	Codice Errore	HTTP Code	Note Aggiuntive
Internal server error (from Fabrick)	VOP-001	500	Internal Server Error – Il servizio VoP di Fabrick è raggiungibile ma temporaneamente non disponibile.
Invalid IBAN	VOP-002	400	Not Valid – Il codice IBAN fornito non è valido.
Invalid X-RequestDateTime	VOP-003	400	Not Valid – Il formato di data/ora non è corretto o non conforme allo standard ISO 8601.
Unsupported OwnerIdentificationType	VOP-004	400	Not Valid – Il tipo di identificazione fornito non è previsto dallo schema VoP.
Malformed message	VOP-005	400	Not Valid – Il messaggio non rispetta il formato previsto.
RequestCode already exists	VOP-006	400	Not Valid – Il codice identificativo fornito non è univoco.
BIC not found	VOP-007	404	Not Valid – Non è stato possibile derivare il BIC dall’IBAN fornito.
Responding PSP not found	VOP-008	404	Not Found – Il PSP non è presente nel registro EDS.
Responding PSP not active	VOP-009	403	Forbidden – Il PSP non è abilitato a gestire richieste VoP come responding PSP.
ID type not supported by Responding PSP	VOP-010	400	Unprocessable Entity – Il PSP non supporta il tipo di controllo richiesto, secondo i dati del registro EDS.
Error response from Responding PSP	VOP-011	400	Bad Request – Il PSP rispondente ha generato un errore in risposta alla richiesta VoP.
Authorisation Issue	VOP-012	401	Unauthorized – Il PSP risponde con codice 401 (es. CLIENT_INVALID o CLIENT_INCONSISTENT).
Internal server error (from Responding PSP)	VOP-013	502	Internal Server Error – Il PSP risponde con codice 500 secondo quanto previsto dalla specifica.

Come già visto nelle sezioni precedenti gli errori vengono restituiti all'interno del vettore errors, come indicato nel seguente esempio:

{
    "status": "KO",
    "errors": [
        {
            "id": "78d2a929-5562-45e2-9883-e3d9e7c49be2",
            "pspProcessingTimes": "300",
            "requestCode": "guid3",
            "operationCode": "bonifico-537",
            "requestDateTime": "2025-02-05T10:15:32.456Z",
            "ownerName": "Riccardo Olivetti",
            "iban": "DE02100100109307118555",
            "description": "description Bonifico",
            "errorCode": "VOP-002",
            "errorDescription": "Responding PSP not found"
        }
    ]
}

Esempio caso bulk con risultati misti: casi in OK e casi con errore:

{
  "status": "OK",
  "payload": {
    "bulkId": 23212,
    "bulkOperationCode": "bonifico-537",
    "bulkRequestCode": "123e4567-e89b-12d3-a456-426614174000",
    "bulkRequestDateTime": "2025-02-05T10:15:32.456Z",
    "list": [
      {
        "id": "b3781739-5fc2-4a2a-9984-998ee4a85bfc",
        "pspProcessingTimes": "300",
        "requestCode": "guid1",
        "operationCode": "bonifico-537",
        "requestDateTime": "2025-02-05T10:15:32.456Z",
        "ownerName": "Mauro Rossi",
        "iban": "DE02100100109307118603",
        "description": "description Bonifico",
        "matchType": "NMTC"
      },
      {
        "id": "0f3bbf52-c52b-462c-933b-0d7c44f6ab40",
        "pspProcessingTimes": "300",
        "requestCode": "guid2",
        "operationCode": "bonifico-537",
        "requestDateTime": "2025-02-05T10:15:32.456Z",
        "iban": "DE02100100109307118777",
        "description": "description Bonifico",
        "matchType": "NMTC",
        "matchedIdentification": {
          "value": "549300DTUYXVMJXZNY75",
          "type": "VERLEI"
        }
      }
    ],
    "errors": [
      {
        "id": "540f6ab4-e7fd-40c1-a7f5-0e76b6ff7484",
        "pspProcessingTimes": "300",
        "requestCode": "guid3",
        "operationCode": "bonifico-537",
        "requestDateTime": "2025-02-05T10:15:32.456Z",
        "ownerName": "Riccardo Olivetti",
        "iban": "DE02100100109307118555",
        "description": "description Bonifico",
        "errorCode": "VOP-002",
        "errorDescription": "Responding PSP not found"
      },
      {
        "id": "941e289a-4bd3-4ed3-9081-580c9e7a0ff6",
        "pspProcessingTimes": "300",
        "requestCode": "guid4",
        "operationCode": "bonifico-537",
        "requestDateTime": "2025-02-05T10:15:32.456Z",
        "iban": "DE02100100109307118888",
        "description": "description Bonifico",
        "ownerIdentification": {
          "value": "5535353546211",
          "type": "VERLEI"
        },
        "errorCode": "VOP-001",
        "errorDescription": "VoP Fabrick service unreachable"
      }
    ]
  }
}

Descrizione flusso e API​

Headers​

Request​

Response​

Lista Types gestiti dal PSP​

Recuperare i dettagli di una richiesta VOP passata​

Ricerca​

Dettagli tramite requesterId​

Modalità Bulk (solo per PSP)​

Verifica Bulk Sincrona​

Verifica Bulk Asincrona​

Polling​

Notificaton S2S​

Gestione degli errori​