Você precisa validar um cartão de pagamento rapidamente, idealmente antes de cobrar ou direcionar a transação. Ao final deste guia, você terá uma chamada funcional que verifica o BIN de um cartão (primeiros 6 dígitos) e retorna marca, tipo, nível, emissor e país usando uma única API Financeira no Zyla API Hub—pronto para colar na sua integração hoje.
O que esta API faz e quando usá-la
A API Card Checker verifica um BIN de 6 dígitos e retorna metadados do cartão, como marca (por exemplo, MASTERCARD), tipo (CREDITO/DEBITO), nível (por exemplo, OURO), nome do emissor e país do emissor. Aplicativos usam isso para:
- Rejeitar marcas ou tipos de cartão não suportados antes da autorização.
- Roteirizar transações para o processador correto com base no país do emissor.
- Pré-preencher informações do emissor para suporte ao cliente ou verificações de conformidade.
- Aprimorar verificações de fraude validando se o BIN é legítimo.
O Zyla API Hub centraliza milhares de APIs de Finanças & Pagamentos sob uma única conta, uma chave de API e um modelo de assinatura. Você pode gerenciar seu acesso e uso entre serviços a partir do seu painel de desenvolvedor em zylalabs.com.
Começando no Zyla API Hub
Para integrar rapidamente:
- Abra a página da API Card Checker no Zyla: Iniciar teste de 7 dias na API Card Checker.
- Clique em Assinar (ou Iniciar Teste Gratuito quando disponível). Para esta API, a primeira API oferece um teste de 7 dias ou 50 solicitações.
- Copie sua chave de API do seu painel. A autenticação é via cabeçalho HTTP: Authorization: Bearer YOUR_API_KEY.
A cobrança é por assinatura + cota (não por chamada). Não há Plano Gratuito. Para opções de acesso e preços atuais, verifique a página da API no Zyla.
Endpoint que você chamará
A API Card Checker fornece um único endpoint simples que valida um BIN e retorna detalhes do cartão. Todas as solicitações são GET e autenticadas com seu token de portador.
Verificar cartão
- Método: GET
- URL: https://zylalabs.com/api/2333/card-checker-api/2243/check-card
- Parâmetro de consulta obrigatório:
- bin (número): os primeiros 6 dígitos do cartão. Exemplo: 444444
O que faz: Valida o BIN fornecido e retorna um payload JSON contendo o status de validação e metadados do cartão (marca, tipo, nível, emissor e país).
cURL que você pode colar e executar
Substitua YOUR_API_KEY pela chave do seu painel Zyla e execute isso no seu terminal:
curl -s -X GET "https://zylalabs.com/api/2333/card-checker-api/2243/check-card?bin=444444" \
-H "Authorization: Bearer YOUR_API_KEY"Exemplo de resposta oficial
{
"status": 200,
"success": true,
"isValid": true,
"message": "O número do BIN é válido.",
"data": {
"bin_iin": "557829",
"card_brand": "MASTERCARD",
"card_type": "CREDIT",
"card_level": "GOLD",
"issuer_name_bank": "AKBANK T.A.S.",
"issuer_bank_website": "------",
"issuer_bank_phone": "4442525",
"iso_country_name": "TURQUIA",
"iso_country_code": "TR"
}
}Campos que você normalmente usará:
- status: código de status semelhante ao HTTP retornado no payload (200 indica sucesso).
- success: indicador booleano de sucesso para a operação da API.
- isValid: se o BIN é reconhecido como válido.
- message: um resultado de validação legível por humanos.
- data.bin_iin: BIN/IIN normalizado retornado pela API.
- data.card_brand: rede do cartão (por exemplo, MASTERCARD, VISA, etc.).
- data.card_type: CREDITO/DEBITO (útil para roteamento ou cálculos de taxas).
- data.card_level: por exemplo, OURO, PLATINA (às vezes usado para lógica de benefícios).
- data.issuer_name_bank: nome do banco emissor.
- data.issuer_bank_phone: telefone do emissor (para fluxos de suporte).
- data.iso_country_name / data.iso_country_code: país do emissor (por exemplo, TR para Turquia).
Exemplo em Python: validar um BIN e lógica de ramificação
Este exemplo chama o mesmo endpoint e usa os campos de resposta para permitir apenas cartões de crédito MASTERCARD emitidos em um país específico. Ajuste a lógica conforme suas necessidades.
import os
import requests
API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
BIN = "444444" # primeiros 6 dígitos do cartão
url = "https://zylalabs.com/api/2333/card-checker-api/2243/check-card"
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()
if not data.get("success"):
raise RuntimeError(f"Verificação do cartão falhou: {data}")
if not data.get("isValid"):
print("BIN não é válido. Bloquear ou voltar.")
else:
meta = data.get("data", {})
brand = meta.get("card_brand")
ctype = meta.get("card_type")
country = meta.get("iso_country_code")
issuer = meta.get("issuer_name_bank")
print(f"BIN válido. Marca={brand}, Tipo={ctype}, Emissor={issuer}, País={country}")
# Política de exemplo: aceitar apenas cartões de crédito Mastercard de TR
if brand == "MASTERCARD" and ctype == "CREDIT" and country == "TR":
print("Prosseguir com o fluxo de autorização.")
else:
print("Roteirizar de forma diferente ou recusar com base nas regras de negócios.")Notas práticas de integração que economizam tempo
- Comprimento do BIN: Apenas os primeiros 6 dígitos são necessários (o endpoint espera um número de 6 dígitos).
- Quando chamar: Execute a verificação o mais cedo possível após coletar os dígitos do cartão, antes de enviar uma autorização para seu PSP.
- Cache: Mapeamentos de BIN para metadados mudam com pouca frequência. Armazene em cache respostas bem-sucedidas (por exemplo, 24 horas a 7 dias) para reduzir latência e uso de cota, e invalide por BIN.
- Privacidade: Você nunca envia PANs completos para esta API—apenas o BIN. Isso reduz o escopo para o manuseio de dados sensíveis em seu serviço.
- Timeouts e tentativas: Use um timeout de cliente razoável (por exemplo, 5–10s). Para problemas de rede transitórios, uma única tentativa com jitter geralmente é suficiente antes de voltar a um fluxo padrão.
- Cotas: Esta API funciona em um modelo de assinatura + cota (não por chamada). Monitore seu uso no seu painel Zyla e agrupe ou armazene em cache para permanecer dentro dos limites do plano.
- Tratamento de falhas: Se o sucesso for falso ou a solicitação falhar, decida se deve permitir uma autorização de melhor esforço ou exigir uma rede/tipo suportado. Registre o payload para auditoria.
- Auditoria: Persista o BIN e os campos de dados de resposta dos quais você depende (marca, tipo, emissor, país) junto com seu registro de tentativa de pagamento para rastreabilidade.
Exemplo de fluxo de ponta a ponta
- O cliente insere o número do cartão em seu formulário de checkout.
- Seu frontend extrai os primeiros seis dígitos (BIN) e os envia para seu backend via TLS.
- Seu backend chama a API Card Checker com esse BIN.
- Se isValid for verdadeiro, use card_brand, card_type e iso_country_code para escolher uma rota de processador ou impor política (por exemplo, apenas CREDITO permitido).
- Armazene em cache o resultado do BIN. Continue com a autorização ou fluxos de 3DS conforme necessário.
Casos de uso que você pode enviar esta semana
- Gatilho de aceitação de cartão: Bloquear marcas ou tipos não suportados cedo para reduzir recusas de gateway a jusante.
- Roteamento baseado em geolocalização: Enviar transações para um processador otimizado para o país do emissor usando iso_country_code.
- Cálculo de taxas: Diferenciar taxas com base em card_type ou card_level (por exemplo, OURO/PLATINA) em sua lógica de preços.
- Ferramentas de suporte: Mostrar issuer_name_bank e telefone para agentes para acelerar escalonamentos.
- Regras de risco: Combinar validade do BIN com verificações de dispositivo, IP e velocidade para aumentar ou diminuir a fricção.
Trabalhando com o endpoint Zyla MCP a partir de agentes de IA
Se você usa ambientes ou agentes de codificação de IA (por exemplo, Claude Code, Cursor, Windsurf), pode chamar as APIs Zyla através da ponte MCP. Configure seu cliente para se conectar ao endpoint Zyla MCP e forneça sua chave de API. Saiba mais aqui: MCP. A partir daí, o agente pode invocar o mesmo endpoint Verificar cartão com o parâmetro bin e seu token de portador por trás das cenas.
Isso permite que você prototipe prompts como “Valide o BIN 444444 e me diga o país do emissor” e conecte o resultado diretamente à sua geração de código ou runbooks—sem sair do seu IDE.
Lista de verificação de testes
- Caminho feliz: Um BIN válido conhecido retorna success=true e isValid=true com campos de dados completos.
- Entrada inválida: Entrada não numérica ou de comprimento errado é rejeitada ou retorna isValid=false (manipule graciosamente em sua UI).
- Ramificação de política: Confirme se suas regras de marca/tipo/país refletem corretamente nos resultados de aceitação e roteamento.
- Cache: Verifique se verificações repetidas para o mesmo BIN atingem o cache e reduzem chamadas de saída.
- Observabilidade: Registre o status, isValid e campos de dados chave; adicione métricas para taxa de acerto de cache e erros da API.
Referência: Resumo do endpoint
- Verificar cartão (GET): https://zylalabs.com/api/2333/card-checker-api/2243/check-card
- Parâmetro obrigatório: bin (número)
- Autenticação: Authorization: Bearer YOUR_API_KEY
- Retorna: status, success, isValid, message e data com metadados BIN/IIN (marca, tipo, nível, emissor, país)
Por que o Zyla API Hub para integrações financeiras
Com mais de 10.000 APIs públicas acessíveis sob uma única conta e uma chave, o Zyla reduz a sobrecarga para equipes que enviam múltiplas integrações. Você pode se inscrever na API Card Checker e combiná-la com outras ferramentas de Finanças & Pagamentos à medida que sua pilha evolui, tudo a partir do seu painel Zyla em zylalabs.com.
FAQ
Posso validar um PAN completo ou apenas o BIN?
Este endpoint valida apenas um BIN de 6 dígitos. Não envie PANs completos. Use seu gateway de pagamento para validação e autorização em nível de PAN.
Qual cabeçalho eu uso para autenticação?
Envie Authorization: Bearer YOUR_API_KEY com cada solicitação.
O que acontece se o BIN não for válido?
A resposta indicará isValid como falso (e o sucesso pode ainda ser verdadeiro se a chamada foi executada). Use esse sinal para ajustar seu fluxo, por exemplo, bloquear o cartão ou solicitar um método de pagamento alternativo.
Quantas solicitações posso fazer?
O Zyla usa assinatura + cota (não por chamada). Para a primeira API, há um teste de 7 dias ou 50 solicitações. Verifique a página da API para limites e preços atuais.
Posso chamar esta API a partir de um agente de IA?
Sim. Conecte seu agente ao endpoint Zyla MCP e autentique com sua chave de API. O agente pode invocar o endpoint Verificar cartão com o parâmetro bin.
Envie sua integração
Valide BINs, roteirize transações de forma inteligente e reduza recusas evitáveis com uma única chamada. Comece aqui e obtenha sua chave: Iniciar teste de 7 dias na API Card Checker. Uma vez inscrito, use o endpoint GET acima com seu token de portador e envie seu fluxo de Finanças esta semana.
