Passa al contenuto principale

Check IBAN via API

Questa modalità di integrazione è invece tramite API. Sarà quindi sufficiente implementare la seguente 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"
  }
}

dove:

  • account: oggetto json contente le informazioni relative al conto
    • value: l'IBAN di cui si vuole verificare la titolarità
    • valueType: tipo di input, ad oggi l'unico valore ammesso è "IBAN"
  • accountHolder: oggetto json contente le informazioni relative all'intestatario del conto
    • fiscalCode: il codice fiscale del titolare del conto, nel caso di persona fisica. Questo campo richiede un codice fiscale italiano. Obbligatorio se accountHolder.type = PERSON_NATURAL.
    • vatCode: il codice IVA del titolare del conto, nel caso di persona giuridica. Questo campo richiede una partita IVA italiana. Obbligatorio se accountHolder.type = PERSON_LEGAL.
    • taxCode: il codice fiscale del titolare del conto, nel caso di persona giuridica. Questo campo richiede un Codice Fiscale Aziendale italiano o un Codice Fiscale italiano (se la persona giuridica è una “Ditta Individuale” o un “Libero Professionista” italiano). Obbligatorio se accountHolder.type = PERSON_LEGAL.
    • type: il tipo di titolare del conto. I valori validi sono PERSON_NATURAL nel caso di persona fisica oppure PERSON_LEGAL nel caso di persona giuridica (sotto forma di società o “Ditta Individuale” o “Libero Professionista” italiana).

In risposta si otterrà

{
  "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
}],
  "warnings": null
}

dove gli oggetti account e accountHolder sono gli stessi oggetti indicati in fase di richiesta, mentre l'oggetto bankInfo contiene le informazioni relative alla banca: presso cui è detenuto il conto:

  • businessName: nome della banca
  • city: città in cui ha sede
  • countryCode: codice paese ISO 3166‑1 alpha‑2
  • bicCode: codice BIC della banca
  • branchName: filiale della banca

Infine l'oggetto validationStatus indica l'esito della verifica tra titolare e IBAN:

  • OK: la banca conferma la corrispondenza
  • KO: la banca non conferma la corrispondenza

Lista banche​

Per conoscere la lista delle banche disponibili per il servizio Check IBAN sarà suffiiciente invocare la seguente API:

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

{}

è possibile utlizzare anche alcuni filtri tramite il body della request:

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

dove:

  • nationalCode: codice nazionale del PSP
  • bicCode: codice BIC del PSP
  • countryCode: codice paese ISO 3166-1 alpha-2
  • name: nome del PSP
  • accountValueType: ad oggi costante di valore IBAN

in risposta si otterrà la lista delle banche disponibili come mostrato nel seguente esempio ed ogni elemnto conterrà le informazioni descritte sopra:

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

Paginazione​

Questa sezione descrive il meccanismo di paginazione

Request​

Se disponibile, la paginazione viene gestita tramite query parameters nella richiesta HTTP:

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

dove

  • offset: è l'Indice (0-based) del primo elemento da restituire, deve essere un intero positivo. Il valore predefinito è 0. Se offset >= resultCount, la risposta sarà vuota, mentre se offset < 0, viene restituito HTTP 400 – Bad Request.
  • limit: indica il numero massimo di elementi da restituire, deve essere un intero positivo. Il valore predefinito 20. Se limit < 0, viene restituito HTTP 400 – Bad Request.
Response​

Se la paginazione è richiesta, la risposta includerà l’oggetto pagination:

{

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

dove

  • pageCount: indica il numero totale di pagine, assumendo che ogni pagina contenga un numero di elementi pari al parametro limit.
  • resultCount: indica il numero totale di elementi disponibili nei risultati.
  • offset: v Request.
  • limit: v Request.