Skip to main content

VoP Responding

Description​

This document describes the technical specifications to be implemented regarding the VoP Responding product. It therefore provides guidelines and information that must be disclosed to Fabrick so that the financial institution can respond in real time to account holder verification requests received from other Payment Service Providers (PSPs) or authorized entities.

Request​

The receiving PSP must expose an endpoint of its choice so that Fabrick can call the verify VoP API using the model shown below:

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

where:

  • owner: indicates the name of the account holder.

  • type: indicates the type of identifier associated with the account holder.

    • NAME – first and last name, or company name.
    • INACNO – Support for additional information on the payment account number.
    • VERLEI – Support for the VERLEI code (Legal Entity Identifier) to identify the payment counterparty.
    • VERBIC – Support for anyBIC to identify the payment counterparty.
    • VCBANK – Support for the identification code of the counterparty bank for the payment.
    • VCCBID – Support for the CBID identification code of the payment counterparty.
    • VCCHID – Support for the CHID identification code of the payment counterparty.
    • VCCINC – Support for the CINC identification code of the payment counterparty.
    • VCCOID – Support for the COID identification code of the payment counterparty.
    • VCCUST – Support for the CUST identification code of the payment counterparty.
    • VCDUNS – Support for the DUNS (Dun & Bradstreet) identification code of the payment counterparty.
    • VCEMPL – Support for the EMPL identification code of the payment counterparty.
    • VCGS1G – Support for the GS1G identification code of the payment counterparty.
    • VCSREN – Support for the SREN identification code of the payment counterparty.
    • VCSRET – Support for the SRET identification code of the payment counterparty.
    • VCTXID – Support for the TXID identification code of the payment counterparty.
    • VCBDID – Support for the BDID identification code of the payment counterparty.
    • VCBOID – Support for the BOID identification code of the payment counterparty.
    • VCPROP – Support for a proprietary code to identify the payment counterparty.

  • iban: IBAN to be verified.

  • respondingBic: BIC of the responding bank.

  • requesterBic: BIC of the requesting bank.

The value of the owner parameter will be determined by the type field — for example, instead of the personal details of a natural person, a company's VAT number could be provided:

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

Headers​

The PSP must also include the following two headers:

X-Request-ID: {GUID}
X-Request-Timestamp: {Timestamp ISO 8601}
  • X-Request-ID: GUID of the VOP request. This is a unique identifier (GUID) associated with the VOP request and is generated by the caller to accurately track and identify the transaction within the system.
  • X-RequestDateTime: timestamp of the VOP request. This field is subject to consistency verification: the date must correspond to the current day and the time must be consistent with the time the request was sent. Otherwise, the call will be rejected.

All headers used in requests will be encoded in UTF-8 to ensure correct interpretation of special characters and compatibility with the system.

Response​

The receiving PSP must provide all the details necessary for Fabrick to run the algorithm matching the IBAN and the account holder and return the final result to the requesting PSP. The necessary information must be provided in accordance with the following model:

{
    "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"
            }
        ]
    }
}

where:

  • iban: IBAN for which you want to identify the owner. Required parameter.

  • resultId: identifier associated with the VOP request; a unique ID generated by the responding PSP. Required parameter.

  • result: final outcome indicating the level of correspondence. Present only when the receiving PSP uses its own algorithm (see next section), in which case it is required. Possible values are:

    • MTCH → Exact match (the name provided matches exactly with the one registered).
    • CMTC → Partial match (the name provided is similar but has minor differences).
    • NMTC → No match (the name provided is not present in the PSP system).
    • NOAP → Unable to verify (verification was not possible due to technical issues).

  • matchedName: present and required only when result equals CMTC. Indicates the account holder registered in the receiving PSP's system.

  • resulDateTime: date and time of request processing (ISO 8601 format). Required parameter.

  • accountHolder: type of account holder; the options will be agreed with the receiving PSP; some examples could be SINGLE, MULTIPLE, CORPORATION. Required parameter only when using Fabrick's match algorithm (see next section).

  • list: list of account holders linked to the IBAN in question. Generally there will be a single element, but there could be two in the case of jointly held accounts. Required parameter only when using Fabrick's match algorithm (see next section). Each element of the list contains the following parameters:

    • owner: only applicable in the case of a legal entity. Indicates the name based on the value of the type parameter; type cannot be NAME.
    • ownerName: applicable for both legal entities and individuals; type can only be NAME. Indicates the first name of the account holder.
    • ownerSurname: only applicable in the case of a natural person, therefore only if type equals NAME. Indicates the last name of the account holder.
    • type: the same parameter passed in the request. Required parameter.
    • matchType: deprecated. Replaced by the result parameter.
    • matchedName: deprecated. It will only be indicated at the root of the object and not within the list.

Match Algorithm​

Fabrick has implemented its own match algorithm, the details of which are described in a dedicated document. The receiving PSP has the option to:

  • leave it unchanged
  • customize certain rules through agreed configurations
  • replace it with its own

As indicated above, depending on whether you use Fabrick's algorithm or your own, the response model may vary. Here are some examples:

Fabrick algorithm – single account holder:

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

Fabrick algorithm – jointly held account:

{
    "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"
            }
        ]
    }
}

Below is an example in which the receiving PSP chooses to apply its own algorithm. The model would be simplified as Fabrick would not need to have information about the account holder, but would simply pass on the final result (result) returned by the PSP. Below is an example with only the mandatory parameters:

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