> ## 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. # API de Verificação de Conta Bancária para Pagamentos > Confirme que uma conta bancária pertence à pessoa ou empresa indicada antes de lhe enviar dinheiro. Sem sessão e sem início de sessão. Didit. > [!NOTE] > > Em produção, a verificação de conta é feita na Nigéria, no Gana e no Quénia. > Outro país responde `404` com `code: country_not_covered` e não é faturado. > Mais países ficarão disponíveis ao longo do tempo, e [Preços da Bank Verification](https://docs.didit.me/pt/getting-started/bank-verification-pricing.md) mostra sempre o que cada país oferece hoje. O seu backend envia o nome e a conta, e lê o resultado. É a [verificação de conta](https://docs.didit.me/pt/core-technology/bank-verification/account-check.md) do passo Bank Verification, sem a intervenção da pessoa. ## Envie a conta no formato que o respetivo país usa | 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": "..."}`, com o código NIP de 6 dígitos do banco (Access Bank é `000014`) e o NUBAN de 10 dígitos | | Gana | `{"bank_code": "...", "account_number": "..."}`, com o código de 3 letras do banco (GCB Bank é `GCB`) | | Quénia | `{"bank_code": "...", "account_number": "..."}`, com o código de 2 dígitos do banco (KCB é `01`) | | México | `{"clabe": "..."}` | | Argentina | `{"cbu_cvu": "..."}` | Alguns países pedem também um `bic` e, para uma conta empresarial, um `registration_id`. Os espaços, traços e pontos são ignorados. Quando uma chave exigida pela verificação do país não é recebida, é devolvido um `400` que a identifica, por exemplo `"field": "account.bank_code", "reason": "required"`. Envie `holder.full_name` para verificar a conta de uma pessoa, ou `holder.business_name` para verificar a conta de uma empresa. ## Envie o consentimento do titular da conta Em alguns países, a verificação de conta precisa do consentimento explícito do titular da conta antes de cada verificação. Peça-o no seu produto e envie depois `"consent": true`. Sem ele, uma verificação nesses países é recusada com um `400` (`field: consent`, `reason: required`) e não é faturada. Noutros países, `consent` é opcional e, quando o envia, a Didit regista-o com a cobrança da verificação. Uma chave de sandbox pede consentimento nos mesmos países que uma chave de produção. ## Leia o resultado | `result` | O que significa | Próximo passo habitual | | - | - | - | | `match` | O banco tem a conta registada com o nome que enviou. | Envie o dinheiro. | | `close_match` | O banco tem a conta em nome semelhante. `holder_name` é esse nome, quando o banco o devolveu. | Compare `holder_name` ou peça à pessoa que confirme. | | `no_match` | O banco tem a conta em outro nome, ou não existe essa conta. | Não envie o dinheiro. | | `cannot_verify` | O banco respondeu sem comparar o nome, por exemplo numa conta bloqueada ou encerrada. | Aplique a sua própria política, por exemplo peça outra conta. | ## Faturação e novas tentativas Cada verificação a que o banco responde é faturada uma vez ao [Preço da verificação de conta](https://docs.didit.me/pt/getting-started/bank-verification-pricing.md) do país da conta, seja qual for o resultado. Um pedido respondido com erro nunca é faturado: um corpo recusado (`400`), falta de crédito (`402`), uma conta para a qual nenhuma verificação está disponível ainda (`404`) ou um banco que não conseguiu responder (`503`). Não existe chave de idempotência nem endpoint para ler uma verificação depois. Um pedido repetido executa uma nova verificação, com um novo `request_id`, e volta a ser faturado, por isso guarde a resposta. A Didit guarda apenas a cobrança, com o ID do pedido, o país, o resultado e a conta mascarada, nunca o nome nem o número completo da conta. ## Teste em sandbox Uma chave de API de sandbox não chama nenhum banco e não é cobrada. Os últimos 4 caracteres do IBAN, ou então do número da conta, escolhem 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 | `match` | Um IBAN, um CLABE e um CBU têm dígitos de controlo: use os [valores de sandbox](https://docs.didit.me/pt/core-technology/bank-verification/account-check.md#testar-na-sandbox) que passam em todas as verificações de formato. ## Acesso Autentique-se com o `x-api-key` da sua aplicação ou com o token bearer de credenciais de cliente. Uma chave de API com âmbito limitado precisa de acesso de escrita às sessões. O endpoint partilha o limite de escrita de 300 pedidos por minuto por chave de API. ## OpenAPI ````yaml pt/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: >- Verifique se uma conta bancária pertence à pessoa ou empresa indicada, antes de lhe enviar fundos. Sem sessão e sem início de sessão: envie o nome e a conta, leia o resultado. Trata-se da [verificação de conta](/pt/core-technology/bank-verification/account-check) do passo Verificação bancária, executada a partir do seu back-end. **O que envia.** O `country` da conta (ISO 3166-1 alfa-3), o `account` no formato em que esse país o escreve e o nome do `holder`: `full_name` para uma pessoa ou `business_name` para uma empresa. O nome de uma empresa verifica uma conta empresarial. **O que recebe em resposta.** O `result` é `match`, `close_match`, `no_match` ou `cannot_verify`. Num `close_match`, `holder_name` é o nome sob o qual o banco detém a conta, quando devolvido pelo banco. O `account` é devolvido mascarado para os seus últimos 4 carateres. **Faturação.** Cada verificação respondida pelo banco é faturada uma vez ao preço de verificação de conta do país da conta, independentemente do resultado: um `no_match`, uma conta que não existe e um `cannot_verify` também são faturados. Um pedido respondido com erro nunca é faturado. **Cada pedido é uma nova verificação.** Não existe chave de idempotência nem endpoint para consultar uma verificação anterior, pelo que um pedido repetido é executado e faturado novamente. Guarde a resposta. **Sandbox.** Use uma chave de API de sandbox com os dados de conta de exemplo. Uma chave de sandbox não contacta nenhum banco e não tem quaisquer custos. Os últimos 4 carateres do IBAN, ou então do número de conta, definem a resposta: `0001` um `close_match` com `holder_name`, `0002` um `close_match` sem este, `0003` e `0006` um `no_match`, `0004` `cannot_verify`, `0005` um `503` e `0009` um `400`. Qualquer outra terminação resulta num `match`. **Chaves de API.** Uma chave de API com âmbitos requer permissões de escrita para sessões. operationId: post_v3_bank_account_check requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckRequest' examples: Person, Nigeria: summary: >- Um código bancário e número de conta, verificados face ao nome de uma pessoa value: country: NGA account: bank_code: '000014' account_number: '0123450001' holder: full_name: Maria Oliveira vendor_data: payout_20481 Company, Nigeria: summary: >- Um código bancário e número de conta, verificados face ao nome de uma empresa value: country: NGA account: bank_code: '000014' account_number: '0123456789' holder: business_name: Northwind Trading Ltd responses: '200': description: >- O banco respondeu. A verificação é faturada, independentemente do resultado. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckResponse' examples: Close match: summary: O banco detém a conta sob um nome aproximado 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: O banco detém a conta sob o nome enviado 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: >- Recusado como enviado e não faturado. `field` indica o campo do corpo a corrigir e `reason` explica o motivo, com as mesmas razões apresentadas no formulário de conta alojado. Apenas o primeiro campo recusado é comunicado. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Missing field: summary: A verificação do país requer um código bancário value: detail: The bank code is not valid (required). code: invalid_account_input field: account.bank_code reason: required Invalid IBAN: summary: O IBAN tem o comprimento incorreto para o respetivo 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 conforme 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 Consent required: summary: >- A verificação de conta do país requer o consentimento do titular da conta 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: A chave de API com âmbito 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 e, por isso, não foi executada. Carregue o seu saldo e envie novamente. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Out of credit: summary: O 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: >- O seu contrato não tem preço para a API de verificação de conta 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 token bearer está em falta ou é inválido, o pedido veio de um endereço fora da lista de IPs da chave, ou uma chave com âmbito 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 válida ou token válido value: detail: You do not have permission to perform this action. No sessions write: summary: Uma chave com âmbito 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 serve esta conta de momento, pelo que nada foi verificado nem faturado. `country_not_covered`: nenhuma serve o respetivo país ou o respetivo tipo de conta (pessoa singular ou empresa) nesse país. `bank_not_covered`: nenhuma serve o respetivo banco. content: application/json: schema: $ref: '#/components/schemas/BankAccountCheckError' examples: Country not covered: summary: Nenhuma verificação de conta serve 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 serve 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 ou faturado; 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": "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: >- O país da conta, como um código ISO 3166-1 alfa-3, por exemplo `NGA`. Minúsculas são aceites. example: NGA account: type: object description: >- A conta tal como o respetivo país a escreve: um `iban`, ou um `account_number` com o código de banco ou de balcão de que o país necessita (`sort_code`, `routing_number`, `transit_institution`, `bsb`, `ifsc`, `bank_code` ou `bic`). O México aceita um `clabe` e a Argentina um `cbu_cvu`, que já identificam o banco. Uma conta empresarial adiciona um `registration_id` onde o país o solicitar. Espaços, traços e pontos são ignorados. As chaves que a verificação do país não utiliza são ignoradas; uma chave de que necessite e não receba resulta num `400` que a identifica. properties: iban: type: string maxLength: 64 description: O IBAN, num país que utiliza IBANs. Deve pertencer a `country`. account_number: type: string maxLength: 64 description: >- O número de conta, num país que regista a conta com um código de banco ou de balcão separado. sort_code: type: string maxLength: 64 description: 'Reino Unido: o código de compensação de 6 dígitos.' routing_number: type: string maxLength: 64 description: 'Estados Unidos: o número de encaminhamento ABA de 9 dígitos.' transit_institution: type: string maxLength: 64 description: 'Canadá: o número de trânsito e da 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 carateres.' bank_code: type: string maxLength: 64 description: O código do banco, onde o país o exige, por exemplo na Nigéria. bic: type: string maxLength: 64 description: O BIC do banco, quando a verificação do país o exige. clabe: type: string maxLength: 64 description: 'México: a CLABE de 18 dígitos. Já identifica o banco.' cbu_cvu: type: string maxLength: 64 description: 'Argentina: o CBU ou CVU de 22 dígitos. Já identifica o banco.' registration_id: type: string maxLength: 64 description: >- O número de registo de uma conta de empresa, nos casos em que o país o exige. additionalProperties: type: string maxLength: 64 example: bank_code: '000014' account_number: '0123450001' holder: $ref: '#/components/schemas/BankAccountCheckHolder' vendor_data: type: string nullable: true description: >- A sua própria referência para esta verificação, devolvida inalterada. example: payout_20481 consent: type: boolean default: false description: >- Defina como `true` quando o titular da conta tiver dado consentimento explícito para esta verificação. Obrigatório nos países cuja verificação de conta exige esse consentimento: sem ele, a verificação é recusada com um erro `400` cujo `field` é `consent` e cujo `reason` é `required`, e nada é faturado. Noutros locais é opcional, e a Didit regista-o com a cobrança da verificação quando o enviar. example: true 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 sob o nome que enviou. `close_match`: sob um nome aproximado, por exemplo, a omissão de um segundo nome ou um erro tipográfico. `no_match`: sob outro nome, ou não existe tal conta. `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: >- Apenas num `close_match`, e apenas quando o banco o devolveu: o nome na conta, tal como consta no banco. Caso contrário, `null`. account: type: string description: A conta, mascarada até aos seus últimos 4 carateres. vendor_data: type: string nullable: true description: A sua própria referência, tal como 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 correu mal, em inglês. code: type: string description: Um código estável para criar ramificações. Ausente em `401` e `403`. field: type: string description: >- Apenas `400`: o campo do corpo a corrigir, como um caminho com pontos, por exemplo `account.sort_code`. reason: type: string enum: - required - length - format - checksum - country_mismatch - rejected description: >- Apenas `400`: o motivo pelo qual o campo foi recusado. `required`, `length`, `format`, `checksum` e `country_mismatch` (um IBAN de outro país) são verificações próprias da Didit; `rejected` significa que o banco recusou a conta tal como enviada. BankAccountCheckHolder: description: >- O nome em relação ao qual a conta é verificada. Envie exatamente um de 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 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 de escrita partilhado de 300 pedidos por minuto por chave de API foi excedido. Respeite o `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: >- A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys. BearerAuth: type: http scheme: bearer description: O token de acesso de credenciais de cliente da aplicação. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.