Como Usar a API Card Checker

Seu checkout precisa sinalizar BINs inválidos antes mesmo de você tocar nas trilhas de pagamento. Ao final deste guia, você validará BINs e lerá instantaneamente a marca do cartão, tipo, nível, emissor e país usando um único HTTP GET para a API Card Checker no Zyla API Hub—pronto para colar no seu backend hoje.

O que esta API oferece

A API Card Checker retorna a validação de um BIN de cartão (Número de Identificação Bancária; os primeiros 6 dígitos) e campos de enriquecimento que você pode usar imediatamente para roteamento, triagem de fraudes e UX:

Ilustração: Como Usar a API Card Checker

isValid e mensagem para confirmar se o BIN fornecido é reconhecido
card_brand (por exemplo, MASTERCARD), card_type (CREDIT/DEBIT) e card_level (por exemplo, GOLD)
issuer_name_bank, issuer_bank_phone, issuer_bank_website
iso_country_name e iso_country_code

É um único endpoint com um único parâmetro obrigatório, projetado para rápida integração em fluxos financeiros, como checkout, roteamento de PSP, regras baseadas em BIN e mensagens específicas do emissor para clientes.

Começando no Zyla API Hub

O Zyla API Hub agrega mais de 10.000 APIs públicas sob uma conta, uma chave de API e um modelo de assinatura + cota. Para começar a usar esta API financeira:

Abra a página da API Card Checker e inscreva-se. Há um teste de 7 dias disponível na listagem. Verifique a página da API para opções de acesso e preços atuais.
Copie sua chave de API.
Chame o endpoint com o cabeçalho Authorization: Bearer YOUR_API_KEY.

Inicie o teste de 7 dias na API Card Checker

Visão geral do endpoint

A API Card Checker tem um endpoint:

Método: GET
URL: https://zylalabs.com/api/2333/card-checker-api/2243/check-card
Parâmetro de consulta obrigatório:
- bin (número): um BIN de 6 dígitos. Exemplo: 444444
Auth: Authorization: Bearer YOUR_API_KEY

Em caso de sucesso, a resposta inclui um status de nível superior, sucesso, isValid, mensagem e um objeto de dados com atributos do emissor e do cartão.

cURL que você pode executar agora

Substitua YOUR_API_KEY pela sua chave do Zyla API Hub e execute:

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 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"
}
}

Notas de campo que você realmente usará:

isValid e mensagem: porta de validação rápida antes de um processamento adicional
data.card_brand / data.card_type / data.card_level: regras de roteamento, badges de UX, lógica de taxas
data.issuer_name_bank e data.issuer_bank_phone: fluxos de suporte cientes do emissor
data.iso_country_code / data.iso_country_name: lógica regional, verificações regulatórias, prompts de SCA

Exemplo em Python (requests)

Este exemplo chama o mesmo endpoint, verifica a validade e ramifica por marca/tipo para lógica de roteamento.

import os
import requests

API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
BIN = "444444"

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=15)
resp.raise_for_status()
data = resp.json()

# Guardrails básicos
if not data.get("success"):
raise RuntimeError(f"Lookup falhou: {data}")

if not data.get("isValid"):
print(f"BIN {BIN} não é válido: {data.get('message')}")
else:
card = data.get("data", {})
brand = card.get("card_brand")
ctype = card.get("card_type")
level = card.get("card_level")
issuer = card.get("issuer_name_bank")
country = card.get("iso_country_code")

print(f"BIN {BIN} é válido: {brand} {ctype} {level} emitido por {issuer} ({country})")

# Lógica de roteamento de exemplo
if brand == "MASTERCARD" and ctype == "CREDIT":
# Roteie para um processador específico ou aplique taxas/límites
pass

# Lógica de UX de exemplo
if country == "TR":
# Cópia localizada ou dicas de SCA para cartões turcos
pass

Dicas de implementação que economizam tempo

Chamadas do lado do servidor apenas. Nunca exponha sua chave de API no código do cliente.
Cache os resultados do BIN por um curto período para reduzir a latência no checkout. Os dados do BIN mudam com pouca frequência, mas sempre projete para revalidação.
Valide o comprimento da entrada: aceite apenas 6 dígitos numéricos para o bin antes de chamar a API.
Use isValid como o primeiro ramo: se falso, falhe rapidamente e solicite ao usuário que verifique novamente seu número do cartão.
Idempotência: Esta solicitação GET é segura para reexecutar em problemas de rede transitórios.

Casos de uso financeiros do mundo real

Pré-validação de checkout: Detecte BINs obviamente incorretos antes de inicializar uma intenção de pagamento.
Roteamento de processador: Roteie por card_brand ou card_type para otimizar taxas de autorização ou taxas.
Risco e conformidade: Use iso_country_code para acionar autenticação em duas etapas ou negar corredores arriscados conforme a política exigir.
UX ciente do emissor: Exiba issuer_name_bank ou forneça issuer_bank_phone em fluxos de suporte.
Controles de método de pagamento: Bloqueie combinações não suportadas (por exemplo, CREDIT corporativo em certas linhas de produtos) usando card_level onde aplicável.

Chamando a partir de agentes de IA via MCP

Se você preferir integrar isso em ferramentas de desenvolvimento de IA (Claude Code, Cursor, Windsurf ou qualquer cliente compatível com MCP), aponte o cliente para o endpoint MCP do Zyla e use sua chave de API Zyla. Seu agente pode então invocar a mesma capacidade da API Card Checker nos bastidores.

Endpoint MCP: MCP
Chave de API: passe sua chave de API Zyla conforme configurado pelo seu cliente MCP
Semântica da chamada: execute a mesma solicitação GET para o caminho check-card com o parâmetro bin

Isso mantém seu fluxo de trabalho no IDE enquanto ainda usa o mesmo cabeçalho Authorization: Bearer YOUR_API_KEY e a URL de solicitação exata mostrada acima.

Lista de verificação de testes

Formato de retorno: Confirme a presença de status, sucesso, isValid, mensagem e campos de dados.* antes de usar os valores.
Validação de entrada: Rejeite BINs não numéricos ou não de 6 dígitos antes de acessar a rede.
Timeouts: Defina um tempo limite de cliente HTTP razoável (por exemplo, 10–15s) e tente novamente apenas em GETs idempotentes.
Observabilidade: Registre o status de nível superior e isValid para triagem; evite registrar PANs completos—apenas os primeiros 6 dígitos para verificações de BIN.
Cache: Cache por BIN; invalide na implantação ou após um período de tempo que se encaixe na sua postura de risco.

FAQ

Qual parâmetro o endpoint requer?
Um único parâmetro de consulta: bin (número de 6 dígitos). Exemplo: bin=444444.

Qual é o endpoint e método exatos?
GET https://zylalabs.com/api/2333/card-checker-api/2243/check-card

Como eu me autentico?
Envie Authorization: Bearer YOUR_API_KEY no cabeçalho da solicitação. Obtenha sua chave na página de assinatura do Zyla API Hub para esta API.

Quais campos são retornados?
Status de nível superior, sucesso, isValid, mensagem e um objeto de dados com bin_iin, card_brand, card_type, card_level, issuer_name_bank, issuer_bank_website, issuer_bank_phone, iso_country_name e iso_country_code.

Há um plano gratuito?
Não há plano gratuito. Um teste de 7 dias está disponível na listagem; verifique a página da API para opções de acesso e preços atuais.

Implemente sua validação de BIN hoje. Inscreva-se na listagem da API Card Checker, pegue sua chave e insira a única chamada GET no seu checkout ou pipeline de risco: Inicie o teste de 7 dias na API Card Checker. Em seguida, expanda para o restante do catálogo financeiro no Zyla API Hub à medida que seu roteiro cresce.