Skip to main content

Check IBAN via API

This integration method is via API. It will therefore be sufficient to implement the following API:

POST {domain}/v4.0/banking-services/account-holders/validate
Auth-Schema: S2S
Apikey: [apiKey]
Content-Type: application/json

{
  "account": {
    "value": "XX00A0000011111200ALWAYSOK",
    "valueType": "IBAN"
  },
  "accountHolder": {
    "type": "PERSON_NATURAL",
    "fiscalCode": "RSSPLA00A28A859V"
  }
}

where:

  • account: JSON object containing account information.
  • value: the IBAN for which ownership is to be verified.
  • valueType: input type; currently, the only permitted value is "IBAN".
  • accountHolder: JSON object containing information about the account holder.
    • fiscalCode: the tax code of the account holder, in the case of a natural person. This field requires an Italian tax code. Required if accountHolder.type = PERSON_NATURAL.
    • vatCode: the VAT code of the account holder, in the case of a legal entity. This field requires an Italian VAT number. Required if accountHolder.type = PERSON_LEGAL.
    • taxCode: the tax code of the account holder, in the case of a legal entity. This field requires an Italian company tax code or an Italian tax code (if the legal entity is an Italian "sole proprietorship" or "freelancer"). Required if accountHolder.type = PERSON_LEGAL.
    • type: the type of account holder. Valid values are PERSON_NATURAL for a natural person or PERSON_LEGAL for a legal entity (in the form of a company or Italian "sole proprietorship" or "freelancer").

The response will be:

{
  "status": "OK",
  "payload": {
    "validationStatus": "OK",
    "account": {
      "value": "XX00A0000011111200ALWAYSOK",
      "valueType": "IBAN",
      "bicCode": null
    },
    "accountHolder": {
      "type": "PERSON_NATURAL",
      "fiscalCode": "RSSPLA00A28A859V",
      "vatCode": null,
      "taxCode": null
    },
    "bankInfo": null
  },
  "errors": [],
  "warnings": null
}

where the account and accountHolder objects are the same objects provided in the request, while the bankInfo object contains information about the bank at which the account is held:

  • businessName: name of the bank.
  • city: city where the bank is headquartered.
  • countryCode: ISO 3166-1 alpha-2 country code.
  • bicCode: BIC code of the bank.
  • branchName: bank branch.

Finally, the validationStatus object indicates the outcome of the verification between the account holder and the IBAN:

  • OK: the bank confirms the correspondence.
  • KO: the bank does not confirm the correspondence.

Bank List​

To view the list of banks available for the Check IBAN service, simply call the following API:

POST /v4.0/banking-services/account-holders/psps/search
Auth-Schema: S2S
Apikey: {{apiKey}}
Content-Type: application/json

{}

It is also possible to apply filters via the request body:

{
  "nationalCode": "12345",
  "bicCode": "ABXXXXXX",
  "countryCode": "IT",
  "name": "PSP name",
  "accountValueType": "IBAN"
}

where:

  • nationalCode: national code of the PSP.
  • bicCode: BIC code of the PSP.
  • countryCode: ISO 3166-1 alpha-2 country code.
  • name: name of the PSP.
  • accountValueType: currently a constant with value IBAN.

The response will contain the list of available banks as shown in the following example, and each element will contain the information described above:

{
  "status": "OK",
  "payload": {
    "list": [
      {
        "nationalCode": "36772",
        "bicCode": "HYEEIT22XXX",
        "countryCode": "IT",
        "name": "HYPE S.P.A.",
        "accountValueType": "IBAN"
      },
      ...
      {
        "nationalCode": "08440",
        "bicCode": "CRCBIT22XXX",
        "countryCode": "IT",
        "name": "Banca di Credito Cooperativo di Carate Brianza",
        "accountValueType": "IBAN"
      }
    ],
    "pagination": {
      "pageCount": 7,
      "resultCount": 137,
      "offset": 0,
      "limit": 20
    },
    "sorting": null
  },
  "errors": [],
  "warnings": null
}

Pagination​

This section describes the pagination mechanism.

Request​

Where available, pagination is managed via query parameters in the HTTP request:

<URI>?offset={offset}&limit={limit}&pagination={pagination}

where:

  • offset: this is the index (0-based) of the first element to be returned; it must be a positive integer. The default value is 0. If offset >= resultCount, the response will be empty, while if offset < 0, HTTP 400 – Bad Request will be returned.
  • limit: indicates the maximum number of elements to return; it must be a positive integer. The default value is 20. If limit < 0, HTTP 400 – Bad Request is returned.
Response​

If pagination is requested, the response will include the pagination object:

{
  …
  "pagination": {
    "pageCount": 50,
    "resultCount": 495,
    "offset": 0,
    "limit": 10
  }
}

where:

  • pageCount: indicates the total number of pages, assuming that each page contains a number of elements equal to the limit parameter.
  • resultCount: indicates the total number of elements available in the results.
  • offset: see Request.
  • limit: see Request.