> ## 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: verificar conta bancária de pagamento > Confirme que uma conta bancária pertence à pessoa ou empresa indicada antes de enviar dinheiro, com a API da Didit. Sem sessão e sem login. > [!WARNING] > > A Verificação bancária ainda não está habilitada em produção. > Até que esteja, este endpoint responde `404` com `code: bank_verification_not_available`, e você não pode adicionar a etapa de Verificação bancária a um fluxo de verificação (workflow) de produção. > Esta página descreve como o endpoint se comporta quando estiver disponível. Seu backend envia o nome e a conta e lê o resultado. É a [verificação de conta](https://docs.didit.me/pt-br/core-technology/bank-verification/account-check.md) da etapa de Verificação bancária, sem incluir a pessoa. ## Envie a conta no formato usado pelo país dela | País | `account` | | - | - | | Países com IBAN | `{"iban": "..."}` | | Reino Unido | `{"sort_code": "...", "account_number": "..."}` | | Estados Unidos | `{"routing_number": "...", "account_number": "..."}` | | Canadá | `{"transit_institution": "...", "account_number": "..."}` | | Austrália | `{"bsb": "...", "account_number": "..."}` | | Índia | `{"ifsc": "...", "account_number": "..."}` | | Nigéria | `{"bank_code": "...", "account_number": "..."}` | | México | `{"clabe": "..."}` | | Argentina | `{"cbu_cvu": "..."}` | Alguns países também exigem um `bic` e, para uma conta empresarial, um `registration_id`. Espaços, hífens e pontos são ignorados. Se faltar uma chave de que a verificação do país precisa, a resposta é um `400` que a identifica, por exemplo `"field": "account.sort_code", "reason": "required"`. Envie `holder.full_name` para verificar a conta de uma pessoa, ou `holder.business_name` para verificar a de uma empresa. ## Leia o resultado | `result` | O que significa | Próximo passo típico | | - | - | - | | `match` | O banco mantém a conta no nome que você enviou. | Envie o dinheiro. | | `close_match` | O banco mantém a conta em um nome parecido. `holder_name` é esse nome, quando informado pelo banco. | Compare `holder_name` ou peça à pessoa que confirme. | | `no_match` | O banco mantém a conta em outro nome, ou a conta não existe. | Não envie o dinheiro. | | `cannot_verify` | O banco respondeu sem comparar o nome, por exemplo no caso de uma conta bloqueada ou encerrada. | Aplique sua própria política, por exemplo peça à pessoa outra conta. | ## Faturamento e novas tentativas Cada verificação respondida pelo banco é cobrada uma vez pelo [preço da verificação de conta](https://docs.didit.me/pt-br/getting-started/bank-verification-pricing.md) do país da conta, qualquer que seja o resultado. Uma requisição respondida com erro nunca é cobrada: um payload recusado (`400`), falta de crédito (`402`), uma conta que ainda não é atendida por nenhuma verificação (`404`) ou um banco que não conseguiu responder (`503`). Não há chave de idempotência nem endpoint para consultar uma verificação depois. Uma requisição tentada novamente executa uma nova verificação, com um novo `request_id`, e é cobrada novamente; por isso, armazene a resposta. A Didit armazena apenas a cobrança, com o ID da requisição, o país, o resultado e a conta mascarada, nunca o nome nem o número completo da conta. ## Teste no sandbox Uma chave de API de sandbox não consulta nenhum banco e não gera cobrança. Os 4 últimos caracteres do IBAN ou, na falta dele, do número da conta definem a resposta: | Termina em | Resposta | | - | - | | `0001` | `close_match`, com um `holder_name` | | `0002` | `close_match`, `holder_name: null` | | `0003`, `0006` | `no_match` | | `0004` | `cannot_verify` | | `0005` | `503`, `account_check_unavailable` | | `0009` | `400`, `reason: rejected` | | Qualquer outro valor | `match` | IBAN, CLABE e CBU têm dígitos verificadores: use os [valores de sandbox](https://docs.didit.me/pt-br/core-technology/bank-verification/account-check.md#teste-no-sandbox) que passam em todas as verificações de formato. ## Acesso Autentique-se com a `x-api-key` da sua aplicação ou com o token bearer de credenciais do cliente dela. Uma chave de API com escopo precisa de permissão de escrita nas sessões. O endpoint compartilha o limite de escrita de 300 requisições por minuto por chave de API. ## OpenAPI ````yaml pt-br/openapi-25.json POST /v3/bank/account-check/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/bank/account-check/: post: tags: - Standalone APIs summary: Verificar uma conta bancária description: >- **Ainda não disponível em produção.** A Verificação bancária está desativada em produção; por isso, até que seja ativada, este endpoint responde `404` com `bank_verification_not_available`. Não construa nada sobre ele ainda. O restante desta descrição explica o que o endpoint faz quando estiver disponível. Confirme que uma conta bancária pertence à pessoa ou à empresa que você indica antes de enviar dinheiro para ela. Sem sessão e sem login: envie o nome e a conta e leia o resultado. É a [verificação de conta](/pt-br/core-technology/bank-verification/account-check) da etapa de Verificação bancária, executada a partir do seu backend. **O que você envia.** O `country` da conta (ISO 3166-1 alpha-3), o `account` no formato usado nesse país e o nome do `holder`: `full_name` para uma pessoa ou `business_name` para uma empresa. Um nome de empresa verifica uma conta empresarial. **O que você recebe.** `result` é `match`, `close_match`, `no_match` ou `cannot_verify`. Em um `close_match`, `holder_name` é o nome sob o qual o banco mantém a conta, quando o banco o retorna. `account` volta mascarado, exceto pelos últimos 4 caracteres. **Faturamento.** Cada verificação respondida pelo banco é cobrada uma vez pelo preço de verificação de conta do país da conta, qualquer que seja o resultado: um `no_match`, uma conta inexistente e um `cannot_verify` também são cobrados. Uma requisição respondida com erro nunca é cobrada. **Cada requisição é uma nova verificação.** Não há chave de idempotência nem endpoint para consultar uma verificação depois; portanto, uma requisição repetida é executada, e cobrada, novamente. Armazene a resposta. **Sandbox.** Onde a Verificação bancária estiver disponível, uma chave de sandbox não chama nenhum banco e não gera cobrança. Os últimos 4 caracteres do IBAN, ou, na falta dele, do número da conta, definem a resposta: `0001` gera um `close_match` com `holder_name`, `0002` um `close_match` sem ele, `0003` e `0006` um `no_match`, `0004` `cannot_verify`, `0005` um `503` e `0009` um `400`. Qualquer outro final gera um `match`. **Chaves de API.** Uma chave de API com escopo precisa de acesso de escrita a sessões. operationId: post_v3_bank_account_check requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckRequest' examples: Person, United Kingdom: summary: >- Um sort code e um número de conta, verificados em relação ao nome de uma pessoa value: country: GBR account: sort_code: 20-45-67 account_number: '31926819' holder: full_name: Maria Oliveira vendor_data: payout_20481 Company, IBAN: summary: Um IBAN, verificado em relação ao nome de uma empresa value: country: DEU account: iban: DE89 3704 0044 0532 0130 00 holder: business_name: Northwind Trading GmbH responses: '200': description: >- O banco respondeu. A verificação é cobrada, seja qual for o resultado. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckResponse' examples: Close match: summary: O banco mantém a conta em um nome semelhante value: request_id: c2f4a9e0-7b1d-4c3a-9e55-1d0a6b8f2a47 result: close_match holder_name: MARIA R OLIVEIRA account: '****6819' vendor_data: payout_20481 created_at: '2026-10-21T14:32:08Z' Match: summary: O banco mantém a conta no nome enviado value: request_id: 5b0e2d7c-41a8-4f6e-9c3b-8e7d1a2f6c90 result: match holder_name: null account: '****3000' vendor_data: null created_at: '2026-10-21T14:35:41Z' '400': description: >- Recusado como enviado e não cobrado. `field` indica o campo do corpo a corrigir e `reason` informa o motivo, com os mesmos motivos exibidos no formulário de conta hospedado. Apenas o primeiro campo recusado é informado. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Missing field: summary: A verificação deste país exige um sort code value: detail: The sort code is not valid (required). code: invalid_account_input field: account.sort_code reason: required Invalid IBAN: summary: O IBAN tem o comprimento incorreto para o seu país value: detail: The iban is not valid (length). code: invalid_account_input field: account.iban reason: length Refused by the bank: summary: O banco recusou a conta como enviada value: detail: The account was refused as typed (rejected). code: invalid_account_input field: account.account_number reason: rejected No name: summary: '`holder` não tem `full_name` nem `business_name`' value: detail: >- Send full_name for a person or business_name for a company. code: invalid_account_input field: holder reason: required '401': description: A chave de API com escopo expirou. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Expired key: summary: A data de validade da chave já passou value: detail: This API key has expired. '402': description: >- A verificação não pode ser paga, por isso não foi executada. Recarregue seu saldo e envie-a novamente. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Out of credit: summary: Seu saldo não cobre uma verificação 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: Seu contrato não tem preço para a API Account check value: detail: >- Your contract does not price the Account check API. Contact your account manager. code: contract_rate_missing '403': description: >- O cabeçalho `x-api-key` ou o bearer token está ausente ou é inválido, a requisição veio de um endereço fora da lista de IPs da chave, ou uma chave com escopo não tem acesso de escrita a sessões. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Missing or invalid credentials: summary: Nenhuma chave de API ou token válido value: detail: You do not have permission to perform this action. No sessions write: summary: Uma chave com escopo sem acesso de escrita a sessões value: detail: This API key has no write access to sessions. '404': description: >- Nenhuma verificação de conta atende esta conta ainda, então nada foi verificado nem cobrado. `country_not_covered`: nenhuma atende o país da conta, ou o tipo de conta (pessoa física ou empresa) nesse país. `bank_not_covered`: nenhuma atende o banco da conta. `bank_verification_not_available`: a Verificação bancária ainda não está habilitada em produção, e essa é a resposta para todas as requisições nesse ambiente até que ela seja ativada. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Country not covered: summary: Nenhuma verificação de conta atende o país value: detail: No account check serves this country yet. code: country_not_covered Bank not covered: summary: Nenhuma verificação de conta atende o banco da conta value: detail: No account check serves this account's bank yet. code: bank_not_covered '429': $ref: '#/components/responses/RateLimitedWrite' '503': description: >- O banco não conseguiu responder. Nada foi verificado nem cobrado; envie a verificação novamente mais tarde. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Unavailable: summary: O banco não respondeu 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": "GBR", "account": {"sort_code": "20-45-67", "account_number": "31926819"}, "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="GBR", account={ "account_number": "31926819", "sort_code": "20-45-67", }, 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: "GBR", account: { account_number: "31926819", sort_code: "20-45-67", }, 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: \"GBR\",\n\tAccount: didit.BankAccountCheckRequestAccount{\n\t\tAccountNumber: didit.String(\"31926819\"),\n\t\tSortCode: didit.String(\"20-45-67\"),\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("GBR") .account(BankAccountCheckRequest.Account.builder() .accountNumber("31926819") .sortCode("20-45-67") .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' => 'GBR', 'account' => [ 'account_number' => '31926819', 'sort_code' => '20-45-67', ], '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: "GBR", account: { account_number: "31926819", sort_code: "20-45-67", }, 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 = "GBR", Account = new() { AccountNumber = "31926819", SortCode = "20-45-67", }, 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: >- O país da conta, como código ISO 3166-1 alfa-3, por exemplo `GBR`. Letras minúsculas são aceitas. example: GBR account: type: object description: >- A conta no formato usado pelo país dela: um `iban`, ou um `account_number` com o código de banco ou de agência que o país exige (`sort_code`, `routing_number`, `transit_institution`, `bsb`, `ifsc`, `bank_code` ou `bic`). O México usa uma `clabe` e a Argentina um `cbu_cvu`, que já identificam o banco. Uma conta empresarial inclui um `registration_id` quando o país exige. Espaços, hifens e pontos são ignorados. Chaves que a verificação do país não usa são ignoradas. Uma chave exigida que não é enviada resulta em um `400` que a identifica. properties: iban: type: string maxLength: 64 description: >- O IBAN, em um país que usa IBANs. Ele deve pertencer a `country`. account_number: type: string maxLength: 64 description: >- O número da conta, em um país que escreve a conta com um código de banco ou de agência separado. sort_code: type: string maxLength: 64 description: 'Reino Unido: o sort code de 6 dígitos.' routing_number: type: string maxLength: 64 description: 'Estados Unidos: o número de roteamento ABA de 9 dígitos.' transit_institution: type: string maxLength: 64 description: 'Canadá: o número de trânsito e instituição de 8 dígitos.' bsb: type: string maxLength: 64 description: 'Austrália: o BSB de 6 dígitos.' ifsc: type: string maxLength: 64 description: 'Índia: o IFSC de 11 caracteres.' bank_code: type: string maxLength: 64 description: >- O código do banco, quando o país exige um, por exemplo na Nigéria. bic: type: string maxLength: 64 description: O BIC do banco, quando a verificação do país exige um. clabe: type: string maxLength: 64 description: 'México: a CLABE de 18 dígitos. Ela já identifica o banco.' cbu_cvu: type: string maxLength: 64 description: >- Argentina: o CBU ou CVU de 22 dígitos. Ele já identifica o banco. registration_id: type: string maxLength: 64 description: >- O número de registro de uma conta empresarial, quando o país exige um. additionalProperties: type: string maxLength: 64 example: sort_code: 20-45-67 account_number: '31926819' holder: $ref: '#/components/schemas/BankAccountCheckHolder' vendor_data: type: string nullable: true description: >- Sua própria referência para esta verificação, retornada sem alterações. example: payout_20481 BankAccountCheckResponse: type: object required: - request_id - result - holder_name - account - vendor_data - created_at properties: request_id: type: string format: uuid description: O ID desta verificação. result: type: string enum: - match - close_match - no_match - cannot_verify description: >- `match`: o banco mantém a conta no nome que você enviou. `close_match`: em um nome parecido, por exemplo sem o nome do meio ou com um erro de digitação. `no_match`: em outro nome, ou essa conta não existe. `cannot_verify`: o banco respondeu sem comparar o nome, por exemplo no caso de uma conta bloqueada ou encerrada. holder_name: type: string nullable: true description: >- Somente em um `close_match`, e somente quando o banco o retornou: o nome na conta, conforme registrado pelo banco. `null` caso contrário. account: type: string description: A conta, mascarada até os 4 últimos caracteres. vendor_data: type: string nullable: true description: Sua própria referência, conforme você a enviou. created_at: type: string format: date-time description: Quando a verificação foi executada, em UTC. BankAccountCheckError: type: object required: - detail properties: detail: type: string description: O que deu errado, em inglês. code: type: string description: >- Um código estável para ramificar sua lógica. Ausente em `401` e `403`. field: type: string description: >- Somente `400`: o campo do corpo a corrigir, como caminho com pontos, por exemplo `account.sort_code`. reason: type: string enum: - required - length - format - checksum - country_mismatch - rejected description: >- Somente `400`: por que o campo foi recusado. `required`, `length`, `format`, `checksum` e `country_mismatch` (um IBAN de outro país) são verificações da própria Didit; `rejected` significa que o banco recusou a conta como enviada. BankAccountCheckHolder: description: >- O nome com o qual a conta é verificada. Envie exatamente um entre `full_name` e `business_name`. oneOf: - $ref: '#/components/schemas/BankAccountCheckPersonHolder' - $ref: '#/components/schemas/BankAccountCheckBusinessHolder' BankAccountCheckPersonHolder: type: object description: A pessoa que deve ser a titular da conta. required: - full_name properties: full_name: type: string maxLength: 255 description: O nome completo da pessoa que deve ser titular da conta. example: Maria Oliveira BankAccountCheckBusinessHolder: type: object description: >- A empresa que deve ser a titular da conta. Verifica uma conta empresarial. required: - business_name properties: business_name: type: string maxLength: 255 description: >- O nome da empresa que deve ser titular da conta. Verifica uma conta empresarial. responses: RateLimitedWrite: description: >- O limite compartilhado de escrita de 300 requisições por minuto por chave de API foi excedido. Respeite `Retry-After` antes de tentar novamente. 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: >- Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys. BearerAuth: type: http scheme: bearer description: O token de acesso de client credentials da aplicação. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.