Saltar para o conteúdo principal
POST
curl
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 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 do passo Bank Verification, sem a intervenção da pessoa.

Envie a conta no formato que o respetivo país usa

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

Faturação e novas tentativas

Cada verificação a que o banco responde é faturada uma vez ao Preço da verificação de conta 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: Um IBAN, um CLABE e um CBU têm dígitos de controlo: use os valores de 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.

Autorizações

x-api-key
string
header
obrigatório

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.

Corpo

application/json
country
string
obrigatório

O país da conta, como um código ISO 3166-1 alfa-3, por exemplo NGA. Minúsculas são aceites.

Required string length: 3
Exemplo:

"NGA"

account
object
obrigatório

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.

Exemplo:
holder
object
obrigatório

O nome em relação ao qual a conta é verificada. Envie exatamente um de entre full_name e business_name.

vendor_data
string | null

A sua própria referência para esta verificação, devolvida inalterada.

Exemplo:

"payout_20481"

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.

Exemplo:

true

Resposta

O banco respondeu. A verificação é faturada, independentemente do resultado.

request_id
string<uuid>
obrigatório

O ID desta verificação.

result
enum<string>
obrigatório

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.

Opções disponíveis:
match,
close_match,
no_match,
cannot_verify
holder_name
string | null
obrigatório

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
string
obrigatório

A conta, mascarada até aos seus últimos 4 carateres.

vendor_data
string | null
obrigatório

A sua própria referência, tal como a enviou.

created_at
string<date-time>
obrigatório

Quando a verificação foi executada, em UTC.

Última modificação em 7 de novembro de 2026