> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Account Check API: verifica conto bancario per pagamenti > Con Didit, verifica che un conto bancario appartenga alla persona o azienda indicata prima di inviare denaro. Nessuna sessione né accesso richiesti. > [!NOTE] > > 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](https://docs.didit.me/it/getting-started/bank-verification-pricing.md) mostrano sempre cosa offre ciascun paese oggi. Il tuo backend invia il nome e il conto, e legge il risultato. È la [verifica del conto](https://docs.didit.me/it/core-technology/bank-verification/account-check.md) del passaggio Bank Verification, senza coinvolgere la persona. ## Invia il conto nel formato usato dal suo paese | Paese | `account` | | - | - | | Paesi con IBAN | `{"iban": "..."}` | | Regno Unito | `{"sort_code": "...", "account_number": "..."}` | | Stati Uniti | `{"routing_number": "...", "account_number": "..."}` | | Canada | `{"transit_institution": "...", "account_number": "..."}` | | Australia | `{"bsb": "...", "account_number": "..."}` | | India | `{"ifsc": "...", "account_number": "..."}` | | Nigeria | `{"bank_code": "...", "account_number": "..."}`, con il codice NIP a 6 cifre della banca (Access Bank è `000014`) e il NUBAN a 10 cifre | | Ghana | `{"bank_code": "...", "account_number": "..."}`, con il codice a 3 lettere della banca (GCB Bank è `GCB`) | | Kenya | `{"bank_code": "...", "account_number": "..."}`, con il codice a 2 cifre della banca (KCB è `01`) | | Messico | `{"clabe": "..."}` | | Argentina | `{"cbu_cvu": "..."}` | 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 | `result` | Significato | Passo successivo tipico | | - | - | - | | `match` | Il conto è intestato al nome che hai inviato. | Invia il denaro. | | `close_match` | Il conto è intestato a un nome simile. `holder_name` è quel nome, quando la banca lo ha restituito. | Confronta `holder_name`, oppure chiedi alla persona di confermare. | | `no_match` | La banca tiene il conto intestato a un altro nome, oppure il conto non esiste. | Non inviare il denaro. | | `cannot_verify` | La banca ha risposto senza confrontare il nome, per esempio per un conto bloccato o chiuso. | Applica la tua politica, per esempio chiedi un altro conto. | ## Fatturazione e nuovi tentativi Ogni controllo a cui la banca risponde viene addebitato una sola volta al [prezzo della verifica del conto](https://docs.didit.me/it/getting-started/bank-verification-pricing.md) 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: | Termina con | Risposta | | - | - | | `0001` | `close_match`, con un `holder_name` | | `0002` | `close_match`, `holder_name: null` | | `0003`, `0006` | `no_match` | | `0004` | `cannot_verify` | | `0005` | `503`, `account_check_unavailable` | | `0009` | `400`, `reason: rejected` | | Qualsiasi altro valore | `match` | Un IBAN, un CLABE e un CBU contengono cifre di controllo: usa i [valori sandbox](https://docs.didit.me/it/core-technology/bank-verification/account-check.md#test-in-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. ## OpenAPI ````yaml it/openapi-25.json POST /v3/bank/account-check/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API di verifica dell'identità. Autenticati con l'intestazione x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/bank/account-check/: post: tags: - Standalone APIs summary: Verifica un conto bancario description: >- Verifica che un conto bancario appartenga alla persona o all'azienda indicata, prima di inviarvi denaro. Nessuna sessione e nessun accesso: invia il nome e il conto, leggi il risultato. È il [controllo del conto](/it/core-technology/bank-verification/account-check) del passaggio Bank Verification, eseguito dal tuo backend. **Cosa invii.** Il `country` del conto (ISO 3166-1 alpha-3), l'`account` nel formato previsto da quel paese e il nome dell'`holder`: `full_name` per una persona fisica o `business_name` per un'azienda. Un nome aziendale verifica un conto aziendale. **Cosa ricevi in risposta.** `result` è `match`, `close_match`, `no_match` o `cannot_verify`. Con `close_match`, `holder_name` è l'intestatario associato al conto dalla banca, qualora quest'ultima lo abbia restituito. L'`account` viene restituito mascherato con solo gli ultimi 4 caratteri visibili. **Fatturazione.** Ogni verifica a cui la banca risponde viene fatturata una volta al prezzo di controllo del conto del paese corrispondente, qualunque sia il risultato: vengono fatturati anche `no_match`, un conto inesistente e `cannot_verify`. Una richiesta a cui viene risposto con un errore non viene mai fatturata. **Ogni richiesta è una nuova verifica.** Non esiste una chiave di idempotenza né un endpoint per rileggere un controllo già eseguito, pertanto una richiesta ripetuta viene eseguita, e fatturata, nuovamente. Salva la risposta. **Sandbox.** Usa una chiave API sandbox con i dati di conto di esempio. Una chiave sandbox non chiama alcuna banca e non prevede addebiti. Gli ultimi 4 caratteri dell'IBAN, o in alternativa del numero di conto, determinano la risposta: `0001` un `close_match` con un `holder_name`, `0002` un `close_match` senza, `0003` e `0006` un `no_match`, `0004` `cannot_verify`, `0005` un `503` e `0009` un `400`. Qualsiasi altra terminazione corrisponde a un `match`. **Chiavi API.** Una chiave API con ambiti richiede l'accesso in scrittura alle sessioni. operationId: post_v3_bank_account_check requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckRequest' examples: Person, Nigeria: summary: >- Un codice bancario e un numero di conto, verificati rispetto al nome di una persona value: country: NGA account: bank_code: '000014' account_number: '0123450001' holder: full_name: Maria Oliveira vendor_data: payout_20481 Company, Nigeria: summary: >- Un codice bancario e un numero di conto, verificati rispetto alla ragione sociale di un'azienda value: country: NGA account: bank_code: '000014' account_number: '0123456789' holder: business_name: Northwind Trading Ltd responses: '200': description: >- La banca ha risposto. Il controllo viene fatturato, qualunque sia il risultato. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckResponse' examples: Close match: summary: La banca detiene il conto sotto un nome simile value: request_id: c2f4a9e0-7b1d-4c3a-9e55-1d0a6b8f2a47 result: close_match holder_name: MARIA R OLIVEIRA account: '****0001' vendor_data: payout_20481 created_at: '2026-10-21T14:32:08Z' Match: summary: La banca detiene il conto sotto il nome inviato value: request_id: 5b0e2d7c-41a8-4f6e-9c3b-8e7d1a2f6c90 result: match holder_name: null account: '****6789' vendor_data: null created_at: '2026-10-21T14:35:41Z' '400': description: >- Rifiutata così come inviata e non fatturata. `field` indica il campo del corpo da correggere e `reason` ne spiega il motivo, con le stesse motivazioni mostrate dal modulo dell'account ospitato. Viene segnalato solo il primo campo rifiutato. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Missing field: summary: La verifica del paese richiede un codice bancario value: detail: The bank code is not valid (required). code: invalid_account_input field: account.bank_code reason: required Invalid IBAN: summary: L'IBAN ha una lunghezza non valida per il rispettivo paese value: detail: The iban is not valid (length). code: invalid_account_input field: account.iban reason: length Refused by the bank: summary: La banca ha rifiutato il conto così come inviato value: detail: The account was refused as typed (rejected). code: invalid_account_input field: account.account_number reason: rejected No name: summary: '`holder` non contiene né `full_name` né `business_name`' value: detail: >- Send full_name for a person or business_name for a company. code: invalid_account_input field: holder reason: required Consent required: summary: >- La verifica del conto nel paese richiede il consenso del titolare del conto value: detail: >- Account checks in this country need the account holder's explicit consent. Ask for it, then send `consent=true`. code: invalid_account_input field: consent reason: required '401': description: La chiave API con ambito è scaduta. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Expired key: summary: La data di scadenza della chiave è stata superata value: detail: This API key has expired. '402': description: >- Il controllo non può essere pagato, pertanto non è stato eseguito. Ricarica il tuo saldo, quindi invialo di nuovo. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Out of credit: summary: Il tuo saldo non copre un controllo value: detail: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me code: insufficient_credits Not in your contract: summary: >- Il tuo contratto non prevede un prezzo per l'API Account check value: detail: >- Your contract does not price the Account check API. Contact your account manager. code: contract_rate_missing '403': description: >- L'intestazione `x-api-key` o il token bearer sono mancanti o non validi, la richiesta proviene da un indirizzo non presente nell'elenco IP della chiave, oppure una chiave con ambito limitato non ha permessi di scrittura per le sessioni. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Missing or invalid credentials: summary: Nessuna chiave API valida o token valido value: detail: You do not have permission to perform this action. No sessions write: summary: >- Una chiave con ambito limitato priva di accesso in scrittura alle sessioni value: detail: This API key has no write access to sessions. '404': description: >- Nessun controllo del conto copre ancora questo conto, pertanto non è stato verificato né fatturato nulla. `country_not_covered`: nessuno copre il relativo paese o quel tipo di conto (persona o azienda) in tale paese. `bank_not_covered`: nessuno copre la relativa banca. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Country not covered: summary: Nessun controllo del conto copre il paese value: detail: No account check serves this country yet. code: country_not_covered Bank not covered: summary: Nessun controllo del conto copre la banca del conto value: detail: No account check serves this account's bank yet. code: bank_not_covered '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: >- La banca non è riuscita a rispondere. Non è stato verificato né fatturato nulla; invia nuovamente il controllo più tardi. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Unavailable: summary: La banca non ha risposto value: detail: >- The account check is temporarily unavailable and this request was not charged. Please try again. code: account_check_unavailable security: - ApiKeyAuth: [] - BearerAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/bank/account-check/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "country": "NGA", "account": {"bank_code": "000014", "account_number": "0123450001"}, "holder": {"full_name": "Maria Oliveira"}, "vendor_data": "payout_20481" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.bank.account_check( country="NGA", account={ "account_number": "0123450001", "bank_code": "000014", }, holder={ "full_name": "Maria Oliveira", }, vendor_data="payout_20481", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.bank.accountCheck({ country: "NGA", account: { account_number: "0123450001", bank_code: "000014", }, holder: { full_name: "Maria Oliveira", }, vendor_data: "payout_20481", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.AccountCheck(ctx, didit.BankAccountCheckRequest{\n\tCountry: \"NGA\",\n\tAccount: didit.BankAccountCheckRequestAccount{\n\t\tAccountNumber: didit.String(\"0123450001\"),\n\t\tBankCode: didit.String(\"000014\"),\n\t},\n\tHolder: didit.BankAccountCheckHolder{\n\t\tFullName: didit.String(\"Maria Oliveira\"),\n\t},\n\tVendorData: didit.String(\"payout_20481\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.BankAccountCheckHolder; import me.didit.types.BankAccountCheckPersonHolder; import me.didit.types.BankAccountCheckRequest; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.bank().accountCheck(BankAccountCheckRequest.builder() .country("NGA") .account(BankAccountCheckRequest.Account.builder() .accountNumber("0123450001") .bankCode("000014") .build()) .holder(BankAccountCheckHolder.ofBankAccountCheckPersonHolder(BankAccountCheckPersonHolder.builder() .fullName("Maria Oliveira") .build())) .vendorData("payout_20481") .build()); System.out.println(result); - lang: php label: PHP source: |- bank->accountCheck([ 'country' => 'NGA', 'account' => [ 'account_number' => '0123450001', 'bank_code' => '000014', ], 'holder' => [ 'full_name' => 'Maria Oliveira', ], 'vendor_data' => 'payout_20481', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.bank.account_check( country: "NGA", account: { account_number: "0123450001", bank_code: "000014", }, holder: { full_name: "Maria Oliveira", }, vendor_data: "payout_20481" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Bank.AccountCheckAsync(new BankAccountCheckRequest { Country = "NGA", Account = new() { AccountNumber = "0123450001", BankCode = "000014", }, Holder = new() { FullName = "Maria Oliveira", }, VendorData = "payout_20481", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: BankAccountCheckRequest: type: object required: - country - account - holder properties: country: type: string minLength: 3 maxLength: 3 description: >- Il paese del conto, come codice ISO 3166-1 alpha-3, ad esempio `NGA`. I caratteri minuscoli sono accettati. example: NGA account: type: object description: >- 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. properties: iban: type: string maxLength: 64 description: >- L'IBAN, in un paese che utilizza gli IBAN. Deve appartenere a `country`. account_number: type: string maxLength: 64 description: >- Il numero di conto, in un paese in cui il conto viene indicato con un codice bancario o di filiale separato. sort_code: type: string maxLength: 64 description: 'Regno Unito: il sort code a 6 cifre.' routing_number: type: string maxLength: 64 description: 'Stati Uniti: il routing number ABA a 9 cifre.' transit_institution: type: string maxLength: 64 description: >- Canada: il numero di transito e dell'istituto, composto da 8 cifre. bsb: type: string maxLength: 64 description: 'Australia: il BSB a 6 cifre.' ifsc: type: string maxLength: 64 description: 'India: codice IFSC di 11 caratteri.' bank_code: type: string maxLength: 64 description: >- Il codice della banca, laddove il paese ne richieda uno, ad esempio in Nigeria. bic: type: string maxLength: 64 description: >- Il BIC della banca, laddove il controllo del paese ne richieda uno. clabe: type: string maxLength: 64 description: 'Messico: la CLABE a 18 cifre. Specifica già la banca.' cbu_cvu: type: string maxLength: 64 description: 'Argentina: il CBU o CVU a 22 cifre. Identifica già la banca.' registration_id: type: string maxLength: 64 description: >- Il numero di registrazione di un account aziendale, laddove il paese ne richieda uno. additionalProperties: type: string maxLength: 64 example: bank_code: '000014' account_number: '0123450001' holder: $ref: '#/components/schemas/BankAccountCheckHolder' vendor_data: type: string nullable: true description: Il tuo riferimento per questo controllo, restituito invariato. example: payout_20481 consent: type: boolean default: false description: >- 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. example: true BankAccountCheckResponse: type: object required: - request_id - result - holder_name - account - vendor_data - created_at properties: request_id: type: string format: uuid description: L'ID di questo controllo. result: type: string enum: - match - close_match - no_match - cannot_verify description: >- `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. holder_name: type: string nullable: true description: >- 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: type: string description: Il conto, mascherato lasciando visibili solo gli ultimi 4 caratteri. vendor_data: type: string nullable: true description: Il tuo riferimento, così come lo hai inviato. created_at: type: string format: date-time description: Data e ora di esecuzione del controllo, in formato UTC. BankAccountCheckError: type: object required: - detail properties: detail: type: string description: Cosa è andato storto, in inglese. code: type: string description: >- Un codice stabile su cui creare diramazioni. Assente su `401` e `403`. field: type: string description: >- Solo per `400`: il campo del corpo della richiesta da correggere, come percorso separato da punti, ad esempio `account.sort_code`. reason: type: string enum: - required - length - format - checksum - country_mismatch - rejected description: >- Solo per `400`: il motivo per cui il campo è stato rifiutato. `required`, `length`, `format`, `checksum` e `country_mismatch` (un IBAN di un altro paese) sono controlli propri di Didit; `rejected` indica che la banca ha rifiutato il conto così come inviato. BankAccountCheckHolder: description: >- Il nome rispetto al quale viene verificato il conto. Invia esattamente uno tra `full_name` e `business_name`. oneOf: - $ref: '#/components/schemas/BankAccountCheckPersonHolder' - $ref: '#/components/schemas/BankAccountCheckBusinessHolder' BankAccountCheckPersonHolder: type: object description: La persona che dovrebbe essere titolare dell'account. required: - full_name properties: full_name: type: string maxLength: 255 description: Il nome completo dell'intestatario previsto per il conto. example: Maria Oliveira BankAccountCheckBusinessHolder: type: object description: >- L'azienda che dovrebbe essere titolare del conto. Verifica un conto aziendale. required: - business_name properties: business_name: type: string maxLength: 255 description: >- Il nome dell'azienda a cui deve essere intestato il conto. Verifica un conto aziendale. responses: RateLimitedWrite: description: >- Il limite di scrittura condiviso di 300 richieste al minuto per chiave API è stato superato. Rispetta `Retry-After` prima di riprovare. content: application/json: schema: type: object required: - detail properties: detail: type: string example: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. BearerAuth: type: http scheme: bearer description: Il token di accesso client-credentials dell'applicazione. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.