Vai al contenuto principale
POST
curl
In produzione, la verifica del conto viene eseguita in Nigeria, Ghana e Kenya. Un altro paese risponde con 404 e code: country_not_covered e non viene addebitato. Altri paesi saranno attivati nel tempo, e Prezzi di Bank Verification mostrano sempre cosa offre ciascun paese oggi.
Il tuo backend invia il nome e il conto, e legge il risultato. È la verifica del conto del passaggio Bank Verification, senza coinvolgere la persona.

Invia il conto nel formato usato dal suo paese

Alcuni paesi richiedono anche un bic, e per un conto aziendale un registration_id. Spazi, trattini e punti vengono ignorati. Un campo di cui il controllo del paese ha bisogno e che non viene fornito produce un 400 che lo indica, per esempio "field": "account.bank_code", "reason": "required". Invia holder.full_name per verificare il conto di una persona, oppure holder.business_name per verificare il conto di un’azienda.

Invia il consenso dell’intestatario del conto

In alcuni paesi la verifica del conto richiede il consenso esplicito dell’intestatario prima di ogni controllo. Richiedilo nel tuo prodotto, poi invia "consent": true. Senza di esso, un controllo in questi paesi viene rifiutato con un 400 (field: consent, reason: required) e non viene addebitato. Altrove consent è facoltativo, e quando lo invii Didit lo registra insieme all’addebito del controllo. Una chiave sandbox richiede il consenso negli stessi paesi di una chiave di produzione.

Leggi il risultato

Fatturazione e nuovi tentativi

Ogni controllo a cui la banca risponde viene addebitato una sola volta al prezzo della verifica del conto del paese del conto, indipendentemente dal risultato. Una richiesta a cui viene risposto con un errore non viene mai addebitata: un corpo rifiutato (400), credito insufficiente (402), un conto per cui nessun controllo è ancora disponibile (404) oppure una banca che non ha potuto rispondere (503). Non esistono una chiave di idempotenza né un endpoint per rileggere un controllo. Una richiesta ritentata esegue un nuovo controllo, con un nuovo request_id, e viene addebitata di nuovo, quindi conserva la risposta. Didit memorizza solo l’addebito, con l’ID della richiesta, il paese, il risultato e il conto mascherato, mai il nome né il numero di conto completo.

Testalo in sandbox

Una chiave API sandbox non chiama nessuna banca e non viene addebitata. Gli ultimi 4 caratteri dell’IBAN oppure, in caso contrario, quelli del numero di conto determinano la risposta: Un IBAN, un CLABE e un CBU contengono cifre di controllo: usa i valori sandbox che superano ogni controllo di formato.

Accesso

Autenticati con l’x-api-key della tua applicazione, oppure con il suo token bearer ottenuto con credenziali client. Una chiave API con ambito limitato richiede l’accesso in scrittura alle sessioni. L’endpoint condivide il limite di scrittura di 300 richieste al minuto per chiave API.

Autorizzazioni

x-api-key
string
header
obbligatorio

La chiave API della tua applicazione, da Developers -> API keys nella Business Console. La chiave primaria ha accesso completo. Una chiave con nome può avere un ambito definito: nessuno, lettura o scrittura per risorsa, limitata ad alcuni workflow o a sessioni approvate, a un elenco di indirizzi IP e a una data di scadenza. 401 indica che la chiave è errata, revocata o scaduta; 403 indica che non è stata inviata alcuna chiave, che la chiave non ha accesso a questa risorsa o azione, oppure che la richiesta proviene da un indirizzo non incluso nel suo elenco IP; 404 su una route di sessione indica che la sessione non rientra nei workflow o negli stati previsti dalla chiave. Una chiave senza accesso ai media riceve gli URL di immagini, video e PDF come null, e una chiave senza permessi di scrittura sulle sessioni riceve link e token di sessione come null. Consulta https://docs.didit.me/console/api-keys.

Corpo

application/json
country
string
obbligatorio

Il paese del conto, come codice ISO 3166-1 alpha-3, ad esempio NGA. I caratteri minuscoli sono accettati.

Required string length: 3
Esempio:

"NGA"

account
object
obbligatorio

Il conto bancario nel formato previsto dal relativo paese: un iban, oppure un account_number accompagnato dal codice bancario o di filiale richiesto dal paese (sort_code, routing_number, transit_institution, bsb, ifsc, bank_code o bic). Il Messico prevede una clabe e l'Argentina un cbu_cvu, che identificano già la banca. Un conto aziendale aggiunge un registration_id laddove il paese lo richieda. Spazi, trattini e punti vengono ignorati. Le chiavi non utilizzate dal controllo del paese vengono ignorate; una chiave necessaria ma assente restituisce un 400 indicandone il nome.

Esempio:
holder
object
obbligatorio

Il nome rispetto al quale viene verificato il conto. Invia esattamente uno tra full_name e business_name.

vendor_data
string | null

Il tuo riferimento per questo controllo, restituito invariato.

Esempio:

"payout_20481"

Imposta su true quando il titolare del conto ha acconsentito esplicitamente a questo controllo. Obbligatorio nei paesi in cui il controllo del conto richiede tale consenso: senza di esso il controllo viene rifiutato con un errore 400 il cui field è consent e il cui reason è required, e non viene addebitato nulla. Altrove è facoltativo e Didit lo registra insieme all'addebito del controllo quando lo invii.

Esempio:

true

Risposta

La banca ha risposto. Il controllo viene fatturato, qualunque sia il risultato.

request_id
string<uuid>
obbligatorio

L'ID di questo controllo.

result
enum<string>
obbligatorio

match: il conto presso la banca è intestato al nome che hai inviato. close_match: a un nome simile, ad esempio con un secondo nome mancante o un refuso. no_match: a un altro nome, oppure il conto non esiste. cannot_verify: la banca ha risposto senza confrontare il nome, ad esempio per un conto bloccato o chiuso.

Opzioni disponibili:
match,
close_match,
no_match,
cannot_verify
holder_name
string | null
obbligatorio

Solo in caso di close_match, e solo se restituito dalla banca: il nome presente sul conto, così come registrato dalla banca. In caso contrario, null.

account
string
obbligatorio

Il conto, mascherato lasciando visibili solo gli ultimi 4 caratteri.

vendor_data
string | null
obbligatorio

Il tuo riferimento, così come lo hai inviato.

created_at
string<date-time>
obbligatorio

Data e ora di esecuzione del controllo, in formato UTC.

Ultima modifica il 7 novembre 2026