Você precisa verificar os detalhes do cartão rapidamente, reduzir tentativas fraudulentas e direcionar pagamentos corretamente—tudo isso sem construir uma pilha completa de inteligência de cartões. Ao final deste artigo, você será capaz de validar o BIN de um cartão de crédito (os primeiros 6 dígitos) e ler de volta os sinais de emissor, marca, tipo e país com a API Validador de Cartão de Crédito - Verificador de BIN no Zyla API Hub.
O que esta API faz e quando usá-la
A API Validador de Cartão de Crédito - Verificador de BIN permite que você valide o BIN de um cartão de crédito (os primeiros seis dígitos) e recupere pontos de dados estruturados úteis para fluxos de trabalho financeiros e de pagamentos. A partir de uma única solicitação GET, você pode saber se um BIN é válido e receber dados como marca do cartão, tipo de cartão, nível, nome do emissor (quando disponível) e sinais do país do emissor. Usos típicos incluem:
- Pré-validação em fluxos de checkout para reduzir recusas mais tarde no ciclo de vida da transação.
- Lógica de roteamento para seleção de PSP ou adquirente por marca ou região do emissor.
- Pipelines de pontuação de risco e fraude combinando inteligência de BIN com geolocalização, dispositivo e verificações de velocidade.
- Enriquecimento em métodos de pagamento armazenados para suportar atendimento ao cliente ou painéis de análise.
Você pode navegar por mais APIs financeiras e de pagamentos no Zyla API Hub, que fornece uma conta, uma chave de API e um modelo de assinatura que cobre milhares de APIs.
Começando no Zyla API Hub
Para enviar sua integração esta semana:
- Abra a lista de APIs: Inicie um teste de 7 dias na API Validador de Cartão de Crédito - Verificador de BIN.
- Clique em Assinar ou Iniciar Teste Gratuito (quando disponível) para obter sua chave de API. A Zyla usa assinatura + cota, não pagamento por chamada.
- Autentique as solicitações com o cabeçalho Authorization: Bearer YOUR_API_KEY.
As opções de acesso geralmente incluem um teste de 7 dias ou 50 solicitações para uma primeira API; verifique a página da API para opções de acesso e preços atuais.
Referência de endpoint
A API Validador de Cartão de Crédito - Verificador de BIN expõe um único endpoint no Zyla:
-
Verificador de BIN
Método: GET
URL: https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker
Propósito: Validar um cartão de crédito com base em seus primeiros seis dígitos (BIN/IIN) e receber detalhes do cartão e do emissor.
Parâmetro de consulta obrigatório:- bin (string, obrigatório): Os primeiros 6 dígitos do número do cartão. Exemplo: 346350
A resposta indica se o BIN é válido e retorna metadados associados, como marca, tipo, nível, dados do emissor e informações do país (se disponíveis).
Exemplo de resposta JSON oficial
Este é o exemplo oficial de carga útil para o endpoint Verificador de BIN. Seus valores reais dependerão do BIN que você consultar.
{
"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:
- status: Código de status no estilo HTTP incluído no corpo.
- success: Booleano indicando o sucesso da solicitação.
- isValid: Se o BIN é reconhecido como válido.
- message: Mensagem de status legível por humanos.
- data.bin_iin: Ecoa o BIN que você consultou.
- data.card_brand: Esquema/rede (por exemplo, AMERICAN EXPRESS, VISA, MASTERCARD).
- data.card_type: CLASSIFICAÇÃO DE CRÉDITO/DEBITO ou similar.
- data.card_level: Nível do produto, se disponível (por exemplo, Platinum). Traços indicam que não foi fornecido.
- data.issuer_name_bank / issuer_bank_website / issuer_bank_phone: Metadados do emissor quando disponíveis. “Apenas API” ou traços indicam disponibilidade via API.
- data.iso_country_name / iso_country_code: Metadados do país quando disponíveis; nulo quando não fornecido.
Mesma resposta (forma compacta)
Aqui está o mesmo exemplo em uma única linha para instantâneas de log ou testes:
{"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 em Python: consultar um BIN e ramificar com base no resultado
O seguinte trecho de Python chama o endpoint, verifica a validade e extrai alguns campos de alto valor para decisões de roteamento ou risco.
import requests
API_KEY = "YOUR_API_KEY"
BIN = "346350"
url = "https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker"
headers = {
"Authorization": f"Bearer {API_KEY}"
}
params = {"bin": BIN}
resp = requests.get(url, headers=headers, params=params, timeout=10)
resp.raise_for_status()
data = resp.json()
if not data.get("success"):
raise RuntimeError(f"Verificação de BIN falhou: {data}")
is_valid = data.get("isValid")
message = data.get("message")
card_info = data.get("data", {}) or {}
brand = card_info.get("card_brand")
card_type = card_info.get("card_type")
issuer = card_info.get("issuer_name_bank")
country_code = card_info.get("iso_country_code")
print(f"isValid={is_valid} message={message}")
print(f"brand={brand} type={card_type} issuer={issuer} country={country_code}")
# Exemplo de ramificação:
if is_valid and brand == "AMERICAN EXPRESS":
# Roteie para um adquirente ou PSP específico para Amex
pass
elif is_valid and card_type == "DEBIT":
# Aplique lógica SCA diferente ou pesos de risco
pass
else:
# Tratamento de fallback para BINs inválidos ou desconhecidos
passMapeamento de campos que você provavelmente usará
- data.card_brand → Roteamento de pagamento, regras de sobretaxa ou ajustes de UI (por exemplo, mostrar logotipo da marca).
- data.card_type → Diferenças na política de risco para cartões de crédito vs. débito.
- data.issuer_name_bank → Ferramentas de atendimento ao cliente ou roteamento baseado em emissor.
- data.iso_country_code → Conformidade baseada em região, fluxos 3DS vs. não-3DS e heurísticas KYC.
Muitas equipes persistem apenas um subconjunto desses campos, especialmente marca, tipo e código do país, juntamente com o BIN para enriquecimento posterior.
Idempotência, tentativas e cache
- Idempotência: GET é seguro para tentar novamente em erros de transporte. Adicione backoff e jitter.
- Cache: Metadados de BIN mudam com pouca frequência. Armazene respostas por BIN (por exemplo, 24 horas ou sua política de operações) para reduzir latência e chamadas.
- Tratamento de nulos: Alguns campos podem ser nulos ou mascarados (por exemplo, “Apenas API”). Trate valores ausentes como desconhecidos e evite suposições frágeis.
- Quotas: A Zyla usa assinatura + cota. Veja a página da API para a alocação do seu plano e opções de acesso atuais.
Casos de uso financeiros do mundo real
- Pré-verificação de BIN no checkout: Assim que o cliente digitar seis dígitos, consulte a API e decida se deve mostrar uma dica de CVV específica da Amex ou um caminho SCA distinto.
- Seleção de adquirente: Prefira diferentes adquirentes por marca ou região do emissor para otimizar taxas de aprovação.
- Defesas contra fraude: Marque regiões incompatíveis (por exemplo, país do BIN vs. país do IP de envio) para verificação adicional.
- Suporte ao cliente: Quando um pagamento falha, exiba a marca e o emissor detectados com base no BIN para acelerar a triagem.
Exemplo de contrato (para testes e simulações)
Ao escrever testes de contrato, você pode afirmar contra esta estrutura conhecida para garantir que os analisadores e validadores a jusante estejam estáveis.
{
"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
}
}Chamando a API de agentes de IA via MCP
Você pode orquestrar esta API dentro de ambientes de codificação de IA que suportam o Protocolo de Contexto de Modelo (MCP), como Claude Code, Cursor ou Windsurf. O endpoint MCP da Zyla centraliza o acesso a qualquer API à qual você se inscreveu usando sua chave Zyla.
- Endpoint: MCP
- Abordagem: Configure seu cliente compatível com MCP com o endpoint MCP da Zyla e sua chave. Instrua o agente a realizar um GET HTTP para a URL do Verificador de BIN com o cabeçalho Authorization definido como Bearer YOUR_API_KEY e o parâmetro de consulta bin=346350.
- Validação: Analise os campos isValid e data do JSON para ramificar a lógica do agente (por exemplo, explique ao desenvolvedor qual roteamento de adquirente usar com base na marca).
Como o MCP centraliza credenciais, você evita embutir chaves em prompts e mantém as chamadas consistentes entre ferramentas.
Lista de verificação operacional
- Segurança: Nunca registre PANs completos. Você só precisa dos primeiros seis dígitos (BIN) para esta API.
- Timeouts: Defina timeouts razoáveis (por exemplo, 5–10 segundos). Tente novamente apenas em erros de rede transitórios.
- Observabilidade: Registre ID da solicitação, BIN e resumo da resposta (status, sucesso, isValid, marca, tipo). Evite registrar PII além do BIN onde a política exigir.
- Resiliência: Se os campos forem nulos, default para fluxos conservadores (por exemplo, exigir 3DS ou verificação adicional).
- Lançamento: Use regras de bloqueio de BIN com sinalização de recurso para que as equipes de produto possam ajustar a lógica sem reimplantar.
Solução de problemas e validação
Se você encontrar nulos inesperados ou valores mascarados, confirme se sua integração está lendo o JSON corretamente e não assumindo campos ausentes. Use o exemplo conhecido para verificar seu analisador:
{
"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
}
}Verificações comuns:
- Ortografia do cabeçalho: Certifique-se de que “Authorization: Bearer YOUR_API_KEY” está exato.
- Parâmetro de consulta: A chave deve ser “bin” e o valor deve ser apenas os primeiros seis dígitos.
- Método HTTP: Deve ser GET para este endpoint.
Fluxo de exemplo de ponta a ponta
- O usuário insere o número do cartão; assim que seis dígitos estão presentes, extraia o BIN.
- GET o endpoint Verificador de BIN com ?bin=346350 e seu cabeçalho de Autorização.
- Na resposta: se sucesso e isValid:
- Armazene marca e tipo para roteamento e UI.
- Se a marca for AMERICAN EXPRESS, ajuste o rótulo do CVV e a rota do adquirente.
- Se iso_country_code for nulo, não assuma roteamento doméstico; trate como desconhecido.
- Se não for válido, solicite ao usuário cedo ou peça um método de pagamento alternativo.
- Cache a resposta indexada pelo BIN para reduzir consultas duplicadas.
Outro par de cURL e JSON oficial para testes rápidos
Use esta solicitação exata e espere a mesma forma abaixo (os valores variarão para outros BINs):
curl -s -X GET "https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker?bin=346350" \
-H "Authorization: Bearer YOUR_API_KEY"{
"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
}
}Por que construir no Zyla API Hub
O Zyla API Hub centraliza autenticação e faturamento em mais de 10.000 APIs públicas. Você usa uma conta, uma chave e faturamento por assinatura + cota para integrar vários serviços rapidamente. Explore APIs financeiras e de pagamentos, incluindo o Verificador de BIN, de um único lugar: zylalabs.com.
FAQ
Esta API retorna uma validação completa de PAN?
Não. Ela valida e enriquece o BIN (os primeiros seis dígitos) e retorna metadados do cartão/emissor. A validação de PAN e CVV é realizada por gateways de pagamento ou adquirentes durante a autorização.
Que autenticação é necessária?
Use o cabeçalho Authorization: Bearer YOUR_API_KEY em cada solicitação. Obtenha sua chave na lista de APIs após se inscrever.
Posso armazenar resultados em cache?
Sim. Os metadados de BIN são relativamente estáveis. Armazene em cache por BIN (por exemplo, 24 horas) para reduzir latência e chamadas, e depois atualize periodicamente.
Quais são os limites e preços do plano?
A Zyla usa assinatura + cota, não pagamento por chamada. A primeira API geralmente oferece um teste de 7 dias ou 50 solicitações. Verifique a página da API para opções de acesso e preços atuais.
Como uso isso a partir de um agente de codificação de IA?
Configure seu cliente compatível com MCP para usar o endpoint MCP da Zyla e sua chave de API. Instrua o agente a fazer uma solicitação GET para a URL do Verificador de BIN com o cabeçalho de Autorização e o parâmetro de consulta bin. Analise os campos isValid e data para guiar as decisões.
Obtenha sua chave e envie
Ative a validação de BIN em minutos. Inscreva-se e obtenha sua chave na lista de APIs: Inicie um teste de 7 dias na API Validador de Cartão de Crédito - Verificador de BIN. Em seguida, chame o endpoint, armazene resultados em cache por BIN e conecte os campos à sua lógica de roteamento de pagamentos e risco.
