Você precisa validar um cartão rapidamente, sem construir seu próprio banco de dados BIN ou manter raspadores de fornecedores. Ao final deste guia, você estará chamando um único endpoint para verificar o BIN de um cartão e lendo de volta atributos-chave como marca, tipo, nível, emissor e país—pronto para integrar ao seu checkout, regras de risco ou fluxos financeiros.
O que você pode fazer com uma verificação de BIN simples
A API Card Checker retorna validação e metadados com base no BIN (Número de Identificação do Banco) de um cartão. Com uma solicitação, você pode saber se o BIN é válido e obter campos como card_brand (por exemplo, MASTERCARD), card_type (por exemplo, CRÉDITO), card_level (por exemplo, OURO), issuer_name_bank e iso_country_code. Equipes de finanças e pagamentos usam isso para:
- Pré-validar cartões antes de tentar a autorização para reduzir chamadas de gateway evitáveis.
- Impor políticas de roteamento ou risco por marca, tipo, nível, emissor ou país.
- Aprimorar logs de transações com detalhes do emissor e país para análises e reconciliações.
- Construir ferramentas de suporte ao cliente que identificam atributos do cartão sem armazenar PANs completos.
A API está listada no Zyla API Hub, um marketplace de APIs com mais de 10.000 APIs públicas. Você obtém uma conta, uma chave de API e um modelo de assinatura + cota nas APIs que escolher—sem surpresas de pagamento por chamada e sem autenticação separada por fornecedor.
Começando no Zyla API Hub
Abra a página da API Card Checker e inscreva-se para obter sua chave. A listagem oferece um teste de 7 dias para que você possa testar em seu ambiente primeiro. Uma vez inscrito, você terá uma chave de API que pode usar em todos os endpoints da Zyla via um cabeçalho de Autorização.
- Iniciar teste de 7 dias na API Card Checker
- Visite a página inicial do hub para explorar outras APIs de Finanças e Pagamentos: zylalabs.com
A autenticação na Zyla é simples: adicione Authorization: Bearer YOUR_API_KEY às suas solicitações. A cobrança é por assinatura + cota, não por chamada. Verifique a página da API para opções de acesso e preços atuais.
O endpoint que você chamará
A API Card Checker expõe um único endpoint simples para validar um BIN e retornar metadados do 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)
Descrição: insira um número BIN de 6 dígitos no parâmetro bin para validar e recuperar os detalhes do cartão.
exemplo de cURL (pronto para copiar e colar)
curl -s -X GET "https://zylalabs.com/api/2333/card-checker-api/2243/check-card?bin=444444" \
-H "Authorization: Bearer YOUR_API_KEY"
Resposta de exemplo oficial
{
"status": 200,
"success": true,
"isValid": true,
"message": "O número 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"
}
}
O que ler a partir deste payload:
- isValid: booleano que indica se o BIN fornecido é reconhecido como válido.
- message: status de validação legível por humanos.
- data.bin_iin: o BIN/IIN associado ao resultado.
- data.card_brand, data.card_type, data.card_level: identificadores úteis para roteamento e rótulos de UI.
- data.issuer_name_bank, issuer_bank_phone, issuer_bank_website: detalhes do emissor que você pode armazenar para referência.
- data.iso_country_name, data.iso_country_code: informações do país para verificações de conformidade e regras de fraude.
Exemplo em Python: verificar um BIN e ramificar na validação
O trecho abaixo demonstra uma chamada GET simples, analisa a resposta e mostra onde integrar sua lógica de política (por exemplo, recusar cartões de crédito pré-pagos, permitir apenas certos países ou solicitar verificação adicional).
import os
import requests
API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://zylalabs.com/api/2333/card-checker-api/2243/check-card"
def check_bin(bin_number: str) -> dict:
url = f"{BASE_URL}?bin={bin_number}"
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(url, headers=headers, timeout=10)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
result = check_bin("444444")
# Campos principais que você usará comumente
is_valid = result.get("isValid")
message = result.get("message")
data = result.get("data", {}) or {}
print("BIN válido:", is_valid)
print("Mensagem:", message)
if is_valid:
brand = data.get("card_brand")
card_type = data.get("card_type")
level = data.get("card_level")
issuer = data.get("issuer_name_bank")
country_code = data.get("iso_country_code")
print("Marca:", brand)
print("Tipo:", card_type)
print("Nível:", level)
print("Emissor:", issuer)
print("País:", country_code)
# Exemplos de ganchos de política:
# - Se você precisar restringir por país:
# if country_code not in {"US", "CA", "GB"}:
# print("Roteie para revisão manual")
# - Se você aceitar apenas certas marcas/tipos:
# if brand != "MASTERCARD" or card_type != "CREDIT":
# print("Mostrar método de pagamento alternativo")
else:
# Fallback quando o BIN não é válido (por exemplo, pedir ao usuário para reentrar)
print("BIN inválido; solicitar correção.")
Notas de implementação que economizam tempo
- Somente o parâmetro de consulta bin é obrigatório. Use os primeiros 6 dígitos do número do cartão; não transmita PANs completos para reduzir a exposição PCI em seus sistemas.
- Desempenho: as buscas de BIN são leves, ideais para serem acionadas em eventos de desfoque em seu formulário de checkout ou do lado do servidor antes da autorização. Considere um cache curto do cliente ou de borda indexado por BIN para reduzir solicitações repetidas durante uma sessão.
- Experiência do usuário de fallback: se isValid for falso, re-prompt o usuário pelos primeiros 6 dígitos. Mantenha o texto de erro neutro: “Por favor, verifique os primeiros 6 dígitos do seu cartão.”
- Normalização: armazene valores de marca/tipo/nível conforme fornecido pela API (por exemplo, MASTERCARD, CRÉDITO) e mapeie-os para quaisquer enums internos em sua camada de fronteira.
- Auditoria: registre a flag isValid, bin_iin, marca, tipo, nível, emissor e iso_country_code em seus logs de auditoria de pagamentos. Evite armazenar o número completo do cartão.
Casos de uso de finanças e pagamentos no mundo real
- Otimização do formulário de checkout: após um usuário digitar os primeiros 6 dígitos, detecte card_brand e mostre o ícone de marca apropriado. Se a marca ou tipo não for suportado, solicite outro cartão antes do evento de envio.
- Regras de roteamento: envie cartões MASTERCARD CRÉDITO OURO para um gateway com a melhor taxa de intercâmbio ou perfil de aceitação para essa marca/tipo.
- Filtros de conformidade: desautorize ou sinalize BINs de países embargados ou não suportados verificando iso_country_code.
- Heurísticas de fraude: combine issuer_name_bank e iso_country_code com geolocalização de IP, país de cobrança e sinais de dispositivo. Incompatibilidades podem aumentar as pontuações de risco.
- Suporte ao cliente: quando um pagamento falha, os agentes de suporte podem rapidamente identificar o emissor e a marca a partir do BIN para orientar os usuários a ligar para seu banco, se necessário.
Chame a mesma API de agentes de IA via MCP
Se você automatiza tarefas usando clientes compatíveis com MCP (por exemplo, assistentes de código que podem chamar ferramentas), você pode invocar as APIs Zyla através do endpoint MCP. Aponte seu cliente para:
https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
A partir daí, instrua o agente a chamar o endpoint da API Card Checker usando o método GET e o parâmetro de consulta bin. Ele passará seu cabeçalho de Autorização automaticamente se seu cliente MCP estiver configurado com a chave da API. Para informações gerais sobre o uso do MCP, consulte a página MCP.
Como integrar em seu fluxo de pagamentos
1) Pré-verificação do lado do cliente (opcional)
Quando o usuário insere os primeiros 6 dígitos, chame seu backend apenas com o BIN. Seu backend então chama a API Card Checker e retorna um payload mínimo (marca, tipo, nível, país). Isso evita expor sua chave da API Zyla ao navegador.
2) Validação do lado do servidor antes da autorização
Logo antes de criar uma intenção de pagamento ou autorização, chame a API com o mesmo BIN para confirmar que é válido e capturar o emissor e o país para seus logs e regras. Se isValid for falso, interrompa a tentativa e peça um cartão diferente.
3) Registro e análises
Armazene campos-chave junto com sua tentativa de transação para que você possa segmentar recusas, aceitação e chargebacks por marca/tipo/emissor/país. Isso ajuda a ajustar o roteamento e os modelos de fraude ao longo do tempo.
Padrões de tratamento de erros
- Camada HTTP: trate não-2xx como transitórios ou terminais com base em sua política de repetição. Timeouts de rede podem ser rapidamente repetidos; 4xx/5xx persistentes devem ser registrados com IDs de correlação.
- Semântica de resposta: use o booleano isValid e a mensagem para fluxos amigáveis ao usuário. Evite analisar issuer_bank_website para roteamento, a menos que tenha um motivo específico—issuer_name_bank e país são motores mais estáveis.
- Resiliência: implemente um backoff exponencial curto com jitter em erros transitórios. Armazene em cache buscas de BIN positivas brevemente para evitar picos repentinos que impactem o checkout.
Notas de segurança e privacidade
- Nunca envie números de cartão completos para seu endpoint de verificação de BIN. Extraia os primeiros 6 dígitos e descarte o resto para esta verificação.
- Mantenha sua chave da API Zyla do lado do servidor; não a incorpore em clientes web ou móveis. Use seu backend como um proxy fino se quiser uma experiência instantânea para o cliente.
- Registre apenas o que você precisa. BIN, marca, tipo, nível, emissor e país são tipicamente suficientes para análise e regras.
Trabalhando dentro das restrições de engenharia
- Orçamento de latência: A verificação de BIN é rápida e pode ser realizada durante a entrada do formulário ou logo antes da autorização. Se você for extremamente sensível à latência, adicione um cache do cliente ou de borda indexado por BIN para um TTL curto.
- Idempotência: A solicitação é uma leitura; considere-a idempotente. Você pode repetir com segurança em falhas transitórias.
- Internacionalização: iso_country_code é ISO alpha-2 (por exemplo, TR). Mapeie-o para sua camada de localização para nomes de exibição ou regras de negócios específicas do país.
Referência: Recapitulação do endpoint
- GET https://zylalabs.com/api/2333/card-checker-api/2243/check-card
- Parâmetro de consulta: bin (número, obrigatório). Exemplo: 444444
- Cabeçalho de autenticação: Authorization: Bearer YOUR_API_KEY
- Campos de resposta que você usará tipicamente: isValid, message, data.bin_iin, data.card_brand, data.card_type, data.card_level, data.issuer_name_bank, data.iso_country_code
Dicas de qualidade de vida para produção
- Ative a integração com um recurso para que você possa implementar por mercado ou segmento.
- Adicione observabilidade: rastreie a contagem de solicitações, taxas de 2xx/4xx/5xx e latência p95 para a verificação de BIN.
- Crie invariantes em testes: simule o JSON acima para verificar sua lógica de roteamento para MASTERCARD CRÉDITO OURO em TR.
- Documente seu mapeamento interno de strings fornecidas pela API (por exemplo, “MASTERCARD”) para seus enums para evitar incompatibilidades silenciosas.
FAQ
Qual é o mínimo que preciso para chamar a API?
Uma chave de API Zyla válida e os primeiros 6 dígitos do cartão (parâmetro bin). Adicione o cabeçalho Authorization: Bearer YOUR_API_KEY.
Posso usar isso no checkout sem armazenar números de cartão completos?
Sim. Envie apenas os primeiros 6 dígitos (BIN). Não envie ou armazene o PAN completo para esta etapa de validação.
Quais campos devo persistir?
Tipicamente: isValid, bin_iin, card_brand, card_type, card_level, issuer_name_bank e iso_country_code. Estes são os mais úteis para roteamento, fraude e relatórios.
Há um plano gratuito?
Não há plano gratuito. A listagem oferece um teste de 7 dias para que você possa avaliar antes de se comprometer. Verifique a página da API para opções de acesso e preços atuais.
Posso chamá-lo de um agente de codificação de IA?
Sim. Configure seu cliente compatível com MCP para usar o endpoint MCP da Zyla, depois faça uma chamada GET para a API Card Checker com o parâmetro bin. Veja a página MCP vinculada acima para detalhes.
Pronto para implementar verificações de cartão em minutos? Abra a listagem e inicie seu teste: Iniciar teste de 7 dias na API Card Checker. Explore mais integrações financeiras em zylalabs.com e implemente seu fluxo de validação esta semana.