Você tem dados de cartão de crédito fluindo para o seu checkout, fluxo de KYC ou sistema de risco, e precisa de uma maneira rápida de validar o BIN (primeiros 6 dígitos) e identificar a marca, tipo e metadados do emissor—esta semana, não no próximo trimestre. Ao final deste artigo, você será capaz de validar um BIN e recuperar informações sobre a marca do cartão, tipo e emissor usando o Validador de Cartão de Crédito - API de Verificação de BIN no Zyla API Hub—completo com cURL e Python para copiar e colar.
O que esta API faz e por que é importante
A API de Validador de Cartão de Crédito - Verificação de BIN retorna metadados para um dado BIN (os primeiros 6 dígitos de um número de cartão). Com uma única solicitação GET, você saberá se o BIN é válido e obterá dados como:
- Marca do cartão (por exemplo, AMERICAN EXPRESS)
- Tipo de cartão (por exemplo, CRÉDITO)
- Nível do cartão quando disponível
- Dados do emissor (quando disponíveis)
- Informações do país (quando disponíveis)
As equipes usam verificações de BIN para pré-validar entradas, selecionar automaticamente elementos da interface do usuário da marca do cartão, aplicar regras adicionais de fraude e direcionar pagamentos. Como a solicitação usa apenas os primeiros 6 dígitos, ela reduz o escopo de PCI em comparação ao envio de PANs completos.
Esta API faz parte da categoria Finanças & Pagamentos no Zyla API Hub, um marketplace com mais de 10.000 APIs públicas sob uma conta, uma chave de API e um modelo de assinatura. Você pode gerenciar seu uso em um só lugar e chamar várias APIs à medida que sua pilha cresce.
Começando no Zyla API Hub
Para experimentar a API de Validador de Cartão de Crédito - Verificação de BIN:
- Abra a lista da API: Inicie um teste de 7 dias na API de Validador de Cartão de Crédito - Verificação de BIN.
- Clique em Inscrever-se ou Iniciar Teste Gratuito (quando disponível). Esta API normalmente suporta um teste de 7 dias para ajudá-lo a construir e testar rapidamente. Verifique a página da API para opções de acesso e preços atuais.
- Copie sua chave de API do seu painel.
Todas as solicitações usam um token Bearer no cabeçalho de Autorização. A cobrança é por assinatura + cota (não por chamada). Não há Plano Gratuito; use o teste para avaliar. Mantenha sua chave segura; não a incorpore em código front-end público.
Visão geral do endpoint
Esta API expõe um endpoint GET para validação de BIN e metadados:
- Método: GET
- URL: https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker
- Parâmetro de consulta:
- bin (string, obrigatório): Primeiros 6 dígitos do cartão (BIN/IIN). Exemplo: 346350
- Auth: Autorização: Bearer SUA_CHAVE_API
Comportamento de alto nível: Você envia um BIN, e a API responde com um código de status, uma flag de sucesso, um campo booleano isValid, uma mensagem e um objeto de dados contendo metadados do cartão. Se alguns atributos não estiverem disponíveis, a resposta refletirá isso com placeholders ou nulos.
cURL que você pode copiar/colar
Aqui está um exemplo completo e funcional contra o endpoint ao vivo. Substitua SUA_CHAVE_API pela sua chave do Zyla API Hub:
curl -s -X GET "https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker?bin=346350" \
-H "Authorization: Bearer SUA_CHAVE_API"Resposta de exemplo oficial
Este é o payload de amostra oficial retornado pelo endpoint ao consultar o BIN 346350:
{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"data": {
"bin_iin": "346350",
"card_brand": "AMERICAN EXPRESS",
"card_type": "CREDIT",
"card_level": "------",
"issuer_name_bank": "------",
"issuer_bank_website": "API Only",
"issuer_bank_phone": "API Only",
"iso_country_name": null,
"iso_country_code": null
}
}Notas de campo que você provavelmente usará:
- status: Código de status numérico semelhante ao HTTP retornado pelo serviço.
- success: Indica que a solicitação foi processada com sucesso.
- isValid: Verdadeiro se o BIN existir e for reconhecido.
- message: Resumo de validação legível por humanos.
- data: Metadados do cartão, onde qualquer informação ausente ou restrita pode ser retornada como placeholders ou nulos.
Exemplo em Python: chamando o endpoint e analisando campos
Este script envia um BIN, verifica a validade e imprime atributos selecionados para lógica de roteamento ou exibição.
import os
import requests
API_KEY = os.getenv("ZYLA_API_KEY", "SUA_CHAVE_API")
BIN = "346350"
url = "https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker"
params = {"bin": BIN}
headers = {
"Authorization": f"Bearer {API_KEY}"
}
resp = requests.get(url, params=params, headers=headers, timeout=10)
resp.raise_for_status()
data = resp.json()
# Verificações básicas de sanidade
if not data.get("success"):
raise RuntimeError(f"API relatou falha: {data}")
# Use isValid para decidir os próximos passos
if data.get("isValid"):
meta = data.get("data", {})
brand = meta.get("card_brand")
ctype = meta.get("card_type")
level = meta.get("card_level")
issuer = meta.get("issuer_name_bank")
country = meta.get("iso_country_name")
print(f"BIN {BIN} é válido.")
print(f"- Marca: {brand}")
print(f"- Tipo: {ctype}")
print(f"- Nível: {level}")
print(f"- Emissor: {issuer}")
print(f"- País: {country}")
else:
print(f"BIN {BIN} não é válido. Mensagem: {data.get('message')}")Exemplos de resposta adicionais que você pode testar
Quando você integrar, mantenha a forma JSON estável em seu parser. Aqui estão exemplos completos adicionais usando o mesmo payload oficial para que você possa verificar logs, persistência e caminhos de teste de forma consistente:
Exemplo para pipelines de logging
{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"data": {
"bin_iin": "346350",
"card_brand": "AMERICAN EXPRESS",
"card_type": "CREDIT",
"card_level": "------",
"issuer_name_bank": "------",
"issuer_bank_website": "API Only",
"issuer_bank_phone": "API Only",
"iso_country_name": null,
"iso_country_code": null
}
}Exemplo para armazenamento (por exemplo, registro Redis/DB)
{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"data": {
"bin_iin": "346350",
"card_brand": "AMERICAN EXPRESS",
"card_type": "CREDIT",
"card_level": "------",
"issuer_name_bank": "------",
"issuer_bank_website": "API Only",
"issuer_bank_phone": "API Only",
"iso_country_name": null,
"iso_country_code": null
}
}Exemplo para serviços de enriquecimento a jusante
{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"data": {
"bin_iin": "346350",
"card_brand": "AMERICAN EXPRESS",
"card_type": "CREDIT",
"card_level": "------",
"issuer_name_bank": "------",
"issuer_bank_website": "API Only",
"issuer_bank_phone": "API Only",
"iso_country_name": null,
"iso_country_code": null
}
}Como integrar isso ao seu fluxo de pagamento ou risco
Padrões práticos que os desenvolvedores implementam em produção:
- Assistência UX do lado do cliente: Assim que um usuário insere os primeiros 6 dígitos, envie o BIN para seu back-end, chame a API e exiba a marca detectada (por exemplo, AMERICAN EXPRESS) para reduzir erros de digitação. Mantenha a chave da API no lado do servidor.
- Regras de roteamento: Use card_type para direcionar transações ou aplicar limites de risco. Por exemplo, trate CRÉDITO de forma diferente de DÉBITO na lógica de pontuação a jusante.
- Portões de KYC/Fraude: Se isValid for falso, bloqueie a tentativa ou exija verificação adicional antes de prosseguir.
- Controles de emissor: Se os dados do emissor estiverem disponíveis, aplique regras de negócios por banco ou país. Seja defensivo: os campos do emissor podem ser restritos ou nulos.
- Cache: Armazene consultas recentes de BIN por horas ou dias (com base na sua tolerância ao risco) para reduzir a latência e o uso da cota. Os metadados do BIN mudam com pouca frequência, mas sempre permita a lógica de atualização.
Validação, segurança e considerações de PCI
Envie apenas o BIN (primeiros 6 dígitos) para este endpoint. Não transmita ou armazene o PAN completo em seus logs. Mantenha os cabeçalhos de Autorização fora dos logs também. Construa um pequeno adaptador do lado do servidor que aceite o BIN do seu cliente, chame esta API e retorne apenas o que você precisa para renderizar. Se você armazenar resultados, armazene apenas os metadados que precisa e sane valores nulos ou de placeholder.
Comportamento ao qual você deve se adaptar
- Campos restritos: Alguns campos do emissor podem ser “Apenas API” ou mascarados. Não assuma um nome/site/telefone do emissor não vazio.
- Tratamento de nulos: Campos de país podem ser nulos; certifique-se de que seu código tolere isso sem lançar exceções.
- Mensagem e status: Use tanto isValid quanto status para construir mensagens ou logs voltados para o usuário.
- Tentativas e timeouts: Defina timeouts razoáveis (por exemplo, 5–10 segundos) e tente novamente apenas em timeouts de rede, não em resultados de validação 4xx.
- Idempotência: Verificações de BIN são somente leitura; você pode tentar novamente falhas de rede com backoff.
Exemplo de ponta a ponta: padrão de middleware
Aqui está um fluxo pragmático que você pode replicar:
- O frontend envia os primeiros 6 dígitos (por exemplo, 346350) para seu servidor via HTTPS.
- Seu servidor chama o endpoint de Verificação de BIN com Autorização: Bearer SUA_CHAVE_API.
- Se success e isValid forem verdadeiros, responda ao cliente com a marca e o tipo para que a interface do usuário reflita “AMERICAN EXPRESS · CRÉDITO”.
- Se não for válido, solicite ao usuário que verifique a entrada antes de permitir qualquer etapa de envio do cartão.
- Opcionalmente, armazene em cache por BIN por um curto TTL para reduzir as viagens de ida e volta em entradas repetidas.
Mapeamento campo a campo para a interface típica de checkout
- Emblema da marca: Use data.card_brand (por exemplo, “AMERICAN EXPRESS”).
- Dica do tipo de cartão: Use data.card_type (por exemplo, “CRÉDITO”).
- Rótulo do emissor: Use data.issuer_name_bank se não for um placeholder; caso contrário, omita.
- Bandeira ou texto do país: Use data.iso_country_name quando disponível.
Sempre proteja contra placeholders (por exemplo, “------”) ou nulos antes de renderizar.
Lista de verificação de testes
- Envie um BIN conhecido e afirme que isValid é booleano.
- Aferir a presença de data.bin_iin corresponde ao BIN consultado.
- Verifique se os campos de marca e tipo são strings e seguros para renderizar.
- Assegure-se de que valores nulos ou de placeholder não quebrem sua interface do usuário ou motor de risco.
- Confirme que o cabeçalho de Autorização está presente em todas as chamadas e nunca registrado.
Trabalhando com agentes de IA via MCP
Se você automatiza fluxos de trabalho com ferramentas de codificação de IA (por exemplo, Claude Code, Cursor, Windsurf), pode chamar as APIs Zyla através do Protocolo de Contexto de Modelo (MCP). Configure seu cliente compatível com MCP para usar o endpoint MCP da Zyla e forneça sua chave de API. Veja os detalhes da integração aqui: MCP. Isso permite que um agente acione o mesmo fluxo de verificação de BIN, enquanto seu servidor ainda controla o armazenamento e registro de chaves. Mantenha os prompts mínimos e valide as saídas antes de agir em fluxos de pagamento.
Dicas operacionais
- Monitoramento: Acompanhe sucesso, status e latência por solicitação. Alerta em picos de falhas.
- Throttling: Implemente limitação de taxa do lado do cliente e backoff exponencial para ser um bom cidadão da API.
- Controle de versão: As respostas do fornecedor podem evoluir; fixe seu parser em campos conhecidos e ignore extras inesperados.
- Ciclo de vida dos dados: Defina TTLs claros nos resultados de BIN em cache e revalide em mudanças significativas na lógica de manipulação de cartões.
Reutilizando a resposta de amostra em diferentes ambientes
Para CI, desenvolvimento local e staging, use o payload de amostra oficial abaixo como um fixture para que você possa testar seus mapeadores e UI sem vazar dados reais de cartão. Mantenha uma única fonte de verdade para a forma.
{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"data": {
"bin_iin": "346350",
"card_brand": "AMERICAN EXPRESS",
"card_type": "CREDIT",
"card_level": "------",
"issuer_name_bank": "------",
"issuer_bank_website": "API Only",
"issuer_bank_phone": "API Only",
"iso_country_name": null,
"iso_country_code": null
}
}Lista de verificação de prontidão para produção
- Variáveis de ambiente: Armazene SUA_CHAVE_API em um gerenciador de segredos.
- Políticas de rede: Permita HTTPS de saída para zylalabs.com para a URL do endpoint.
- Tentativas limitadas no tempo: Tente novamente apenas erros de rede; não tente novamente falhas de validação.
- Observabilidade: Registre IDs de solicitação e respostas filtradas (sem segredos) para auditorias.
- Controle de acesso: Limite quais serviços podem chamar o verificador de BIN para reduzir riscos laterais.
Armadilhas comuns e como evitá-las
- Chamadas do lado do cliente com chaves expostas: Sempre faça proxy via seu servidor.
- Assumindo que o emissor ou país está sempre presente: Lide com placeholders e nulos de forma elegante.
- Parsing apenas texto de mensagem: Use isValid e status para lógica; a mensagem é para humanos.
- Cache obsoleto: Defina TTLs razoáveis e invalide se detectar metadados inconsistentes.
Para onde ir a seguir
Navegue por outras APIs de Finanças & Pagamentos e consolide suas integrações sob uma conta no Zyla API Hub. Mantenha seus casos de uso de risco, pagamentos e relatórios em um único ecossistema com uma única chave de API e assinatura.
FAQ
A API valida números de cartão completos?
Não. O endpoint valida um BIN (primeiros 6 dígitos) e retorna metadados associados. Não envie PANs completos.
Que autenticação é necessária?
Envie Autorização: Bearer SUA_CHAVE_API no cabeçalho de cada solicitação.
Há um plano gratuito?
Não há Plano Gratuito. Verifique a lista da API para acesso atual. Um teste de 7 dias está tipicamente disponível para avaliar o serviço.
Com que frequência devo armazenar em cache os resultados do BIN?
Os metadados do BIN mudam com pouca frequência. Armazene em cache de acordo com sua postura de risco e cronograma de atualização. Sempre trate nulos/placeholders ao atualizar.
Como faço para chamar isso de um agente de IA?
Use um cliente compatível com MCP e aponte para o endpoint MCP da Zyla documentado aqui: MCP. Mantenha as chaves em um armazenamento seguro e valide as saídas antes de agir.
Pronto para implementar a validação de BIN? Inicie sua avaliação e obtenha uma chave de API no marketplace: Inicie um teste de 7 dias na API de Validador de Cartão de Crédito - Verificação de BIN.
