IBAN de teste para programadores e QA

Qualquer código que aceite, guarde ou envie IBAN precisa de dados de teste: validação de formulários, fluxos de onboarding, fixtures de base de dados, integrações de pagamento, testes de carga. Os IBAN reais de clientes não têm lugar num ambiente de teste, e os IBAN escritos à mão raramente têm dígitos de controlo corretos. Um IBAN de teste, a que por vezes se chama IBAN falso ou fictício, resolve os dois problemas: passa na validação estrutural e nenhum banco o emitiu.

O que um validador verifica

A validação de um IBAN faz-se por camadas. Cada camada apanha problemas diferentes, e um IBAN de teste só passa em algumas delas.

As duas últimas verificações precisam de dados dos bancos. No Reino Unido, o Confirmation of Payee compara o nome do titular da conta com o nome indicado pelo ordenante; na zona euro, a verificação do beneficiário faz o mesmo antes de uma transferência. Um IBAN aleatório não consegue passar nessas verificações, e não deve passar. Dígitos de controlo nacionais no IBAN explica a camada nacional, país a país.

As cinco primeiras verificações, mais os dígitos de controlo nacionais quando a regra é conhecida, não precisam de dados externos. O nosso validador de IBAN faz estas verificações no seu navegador e mostra qual falha. A nossa biblioteca JavaScript de código aberto iban-check faz as cinco segundo o registo IBAN da SWIFT e devolve um código de erro que indica qual falhou. A Argélia e Marrocos não constam do registo, por isso rejeita os respetivos IBAN. Está disponível no npm como iban-check.

Erros comuns no tratamento de IBAN

Estes são os bugs que aparecem uma e outra vez em código que trata IBAN:

• Um único comprimento para todos os países. Os IBAN alemães têm 22 caracteres, mas os noruegueses têm 15 e os malteses 31. Valide o comprimento por país, e não com um número fixo.
• Só dígitos depois do código de país. Os IBAN neerlandeses, britânicos e muitos outros têm letras no BBAN (NL91ABNA0417164300). Uma regex que só aceite dígitos rejeita-os.
• Guardar o formato impresso. Guarde os IBAN no formato eletrónico, sem espaços e em maiúsculas, e acrescente os espaços só quando os mostrar.
• Tratar o IBAN como um número. Contém letras e o BBAN pode começar por zeros. Guarde-o como string.
• Overflow de inteiros no MOD-97. Exceto na Noruega e na Bélgica, o número convertido não cabe num inteiro de 64 bits (cerca de 19 dígitos); o de um IBAN alemão tem 24. Use precisão arbitrária ou o cálculo do resto por partes mostrado em Como funcionam os dígitos de controlo do IBAN.
• Caracteres invisíveis vindos de copiar e colar. Os utilizadores colam IBAN com espaços não separáveis, tabulações ou quebras de linha. Retire todos os caracteres de espaço em branco, e não apenas o espaço normal.
• Entrada em minúsculas. As pessoas escrevem de89.... Converta para maiúsculas antes de validar.

Que IBAN de teste usar

Os IBAN de teste aleatórios servem para a maioria dos testes: validação de formulários, fixtures, dados iniciais (seed data), testes de carga e capturas de ecrã. Use vários países, e não só o seu, para pôr à prova o tratamento do comprimento e do padrão; formatos longos como o de Malta (31) e curtos como o da Noruega (15) são bons casos-limite. Por omissão, o gerador está no modo realista: apenas dígitos e, quando disponível, o código de um banco real, com um número de conta aleatório, por isso o código que verifica o banco encontra-o. Um IBAN destes também não foi emitido por nenhum banco, mas pode coincidir por acaso com uma conta real. Desative a opção Realista para obter IBAN totalmente aleatórios: o código do banco também é aleatório, o que serve para testar um banco desconhecido, e podem aparecer letras onde o formato as permite.

Os prestadores de serviços de pagamento publicam muitas vezes os seus próprios IBAN de teste, que provocam resultados específicos no respetivo ambiente de testes (sandbox), como um débito bem-sucedido ou falhado. Quando testar de ponta a ponta o fluxo de um prestador, use os IBAN da documentação desse prestador.

Nunca use o IBAN de uma pessoa real em testes, demonstrações ou documentação, e nunca envie dinheiro para um IBAN gerado. A probabilidade de um IBAN aleatório coincidir com uma conta real é muito pequena, mas não é nula.

Levar IBAN de teste para o seu pipeline

O gerador mostra um IBAN com os segmentos explicados. A opção "Gerar uma lista" cria de uma vez 5 a 100 IBAN de um país, para copiar ou guardar num ficheiro CSV, JSON, SQL ou de texto simples, com uma coluna por segmento. Para testes automatizados:

• A API REST devolve até 100 IBAN válidos por pedido para qualquer país suportado, e também valida IBAN. Precisa de uma chave de API; consulte a documentação da API.
• O servidor MCP público permite que agentes de IA e assistentes de programação gerem e validem IBAN de teste sem chave.
• O ficheiro de "Gerar uma lista" vem de um URL simples que não precisa de chave, por isso um script pode obter diretamente um ficheiro de fixtures (até 30 por minuto).
• Para testes que têm de correr sem acesso à rede, gere uma vez um conjunto de IBAN e guarde-os no repositório como fixtures.

# 50 IBAN neerlandeses em CSV, sem chave
curl -o fixtures.csv "https://generaterandomiban.com/export/nl?format=csv&count=50"

# 5 IBAN da API, com chave
curl -H "X-API-Key: YOUR_KEY" \
  "https://generaterandomiban.com/api/v1/generate/NL?count=5"

Fontes

• SWIFT IBAN Registry: o comprimento e a estrutura do BBAN de cada país.
• ISO 13616-1:2020: a estrutura do IBAN.
• ISO/IEC 7064: o método de dígitos de controlo MOD 97-10.
• Regulamento (UE) 2024/886: a verificação do beneficiário nas transferências em euros.