Você precisa validar e enriquecer os BINs de cartões esta semana para que possa sinalizar pagamentos arriscados, direcionar transações corretamente ou preencher dados do emissor em sua pilha financeira. Ao final deste guia, você fará solicitações autenticadas à API Card Checker no Zyla API Hub, interpretará a resposta de forma confiável e a integrará em um checkout de produção ou fluxo de risco.
O que a API Card Checker faz
A API Card Checker verifica o BIN (Número de Identificação do Banco, os primeiros 6 dígitos de um número de cartão) e retorna detalhes do emissor e da rede. Com uma única chamada GET, você saberá se o BIN é válido e recuperará campos estruturados, incluindo marca do cartão, tipo, nível, nome do emissor, telefone do emissor e informações do país ISO. As equipes usam isso para:
- Validar BINs no checkout antes de tentar a autorização.
- Identificar marcas de cartões (por exemplo, MASTERCARD) e tipos (por exemplo, CRÉDITO) para lógica de roteamento e conformidade.
- Impulsionar a pontuação de risco com sinais do país do emissor (por exemplo, comparar com o país de cobrança).
- Potencializar ferramentas de suporte que mostram rapidamente qual banco emitiu um cartão.
Começando no Zyla API Hub
A API Card Checker está disponível no Zyla API Hub, que hospeda mais de 10.000 APIs públicas em finanças e categorias relacionadas. Você se inscreve uma vez, recebe uma única chave de API e chama o endpoint pronto para uso imediatamente. A primeira API que você tenta inclui um teste de 7 dias ou 50 solicitações, com assinatura + cota (não paga por chamada). Verifique a página da API para opções de acesso e preços atuais.
- Abra a lista de APIs e inscreva-se: Iniciar teste de 7 dias na API Card Checker.
- Copie sua chave de API.
- Use Authorization: Bearer YOUR_API_KEY em cada solicitação ao endpoint documentado abaixo.
Referência do endpoint
Verificar cartão
Método: GET
URL: https://zylalabs.com/api/2333/card-checker-api/2243/check-card
Descrição: Valida um BIN de 6 dígitos e retorna metadados do emissor e da rede.
Parâmetro de consulta obrigatório:
- bin (número): O BIN de 6 dígitos. Exemplo: 444444
Exemplo de cURL (copiar/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 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"
}
}O que você normalmente usará deste payload:
- isValid: Flag booleana indicando que o BIN é reconhecido e válido.
- data.bin_iin: O BIN/IIN retornado para a consulta (string).
- data.card_brand: Rede/marca (por exemplo, MASTERCARD).
- data.card_type: Categoria do produto do cartão (por exemplo, CRÉDITO).
- data.card_level: Nível/tier (por exemplo, GOLD) se disponível.
- data.issuer_name_bank: Nome do banco emissor.
- data.issuer_bank_phone: Telefone de contato do emissor.
- data.iso_country_name / iso_country_code: País do emissor (nome e código ISO alpha-2).
Exemplo em Python
Este exemplo chama o endpoint, verifica a validade e imprime os campos que você pode usar para regras de checkout ou pontuação de risco. Substitua YOUR_API_KEY pela sua chave.
import requests
API_KEY = "YOUR_API_KEY"
BASE_URL = "https://zylalabs.com/api/2333/card-checker-api/2243/check-card"
def fetch_bin_info(bin_number: str) -> dict:
headers = {
"Authorization": f"Bearer {API_KEY}"
}
params = {
"bin": bin_number
}
resp = requests.get(BASE_URL, headers=headers, params=params, timeout=10)
# Se o Hub retornar um HTTP não-200, levante para visibilidade em logs/alertas.
resp.raise_for_status()
return resp.json()
def main():
# Exemplo de BIN
bin_number = "444444"
data = fetch_bin_info(bin_number)
# Verificações mínimas que você deve realizar antes de usar os campos
if not data.get("success"):
print("Consulta não bem-sucedida:", data)
return
print("BIN válido:", data.get("isValid"))
info = data.get("data", {}) or {}
print("BIN/IIN resolvido:", info.get("bin_iin"))
print("Marca:", info.get("card_brand"))
print("Tipo:", info.get("card_type"))
print("Nível:", info.get("card_level"))
print("Emissor:", info.get("issuer_name_bank"))
print("Telefone do emissor:", info.get("issuer_bank_phone"))
print("País do emissor:", info.get("iso_country_name"), "(", info.get("iso_country_code"), ")")
# Exemplo: regra de risco leve
# if info.get("iso_country_code") not in {"US", "CA", "GB"}:
# flag_reason = "issuer_country_out_of_region"
if __name__ == "__main__":
main()Notas de implementação que economizam tempo
- Autorização: Sempre envie Authorization: Bearer YOUR_API_KEY exatamente como mostrado. Não coloque a chave em parâmetros de consulta.
- Formato do BIN: O endpoint espera um BIN de 6 dígitos no parâmetro de consulta bin. Remova espaços, não dígitos e evite enviar PANs completos; apenas o BIN é necessário.
- Cache: Mapeamentos de BIN para emissor são relativamente estáveis. Armazene em cache os resultados indexados por BIN em seu sistema para reduzir chamadas repetidas e latência. Invalide quando você observar mudanças de emissor em seus logs.
- Fallbacks suaves: Se success for falso ou isValid for falso, mantenha seu checkout responsivo. Por exemplo, você pode recorrer a um tratamento genérico de cartões e prosseguir para a autorização enquanto aumenta a monitorização.
- Registro: Registre data.bin_iin e campos do emissor para observabilidade. Evite registrar números de cartões completos; você deve lidar apenas com o BIN para esta consulta.
- Teste: Use uma mistura de BINs comuns entre marcas e regiões para verificar se sua lógica de roteamento ou risco lida com diferentes combinações de marca/tipo/nível/país.
Fluxos de trabalho financeiros comuns que você pode implementar com esta API
- Pré-validação de checkout: Chame a API após formatar a entrada do cartão e antes de criar uma intenção de pagamento. Rejeite BINs obviamente inválidos cedo ou exija verificação adicional para emissores específicos.
- Correspondência de país do emissor: Compare iso_country_code com o país de cobrança ou IP para acionar autenticação de passo quando não corresponderem.
- Dicas de roteamento de rede: Direcione MASTERCARD vs. outras marcas para diferentes adquirentes ou aplique políticas 3DS personalizadas por card_type.
- Enriquecimento de suporte ao cliente: Quando uma cobrança falha com uma recusa genérica, mostre issuer_name_bank e issuer_bank_phone no console do agente para acelerar a resolução.
- Análise e monitoramento: Agregue transações por issuer_name_bank ou iso_country_code para rastrear desempenho e padrões de chargeback.
Tratamento de erros e resiliência
A resposta de exemplo demonstra uma consulta bem-sucedida com status: 200 e success: true. Na sua integração:
- Verifique os códigos de status HTTP e trate respostas não-2xx de forma apropriada (tente novamente com backoff se necessário, dependendo da sua fila de trabalho ou estratégia de checkout).
- Inspecione success e isValid antes de usar campos de dados. Se qualquer uma das verificações falhar, continue com padrões conservadores.
- Valide se os dados existem antes de ler campos aninhados para evitar problemas de None/KeyError.
Dicas de segurança e conformidade
- Envie apenas o BIN (6 dígitos). Não transmita PANs completos para este serviço.
- Armazene sua chave de API em segredos do lado do servidor (por exemplo, variáveis de ambiente ou um gerenciador de segredos). Não a exponha no código do lado do cliente.
- Registre detalhes mínimos necessários e evite PII nos logs. O BIN em si não é suficiente para identificar um titular de cartão, mas combine-o cautelosamente com outros atributos em seu sistema.
Chamando a API de agentes de IA via MCP
Você pode invocar APIs no Zyla através de um cliente compatível com MCP usando o endpoint MCP. Aponte seu cliente MCP para a seguinte URL e inclua sua chave de API Zyla:
A partir daí, seu agente de IA pode chamar o mesmo endpoint da API Card Checker conforme mostrado acima usando o cabeçalho Authorization. Use o agente para automatizar o enriquecimento de dados (por exemplo, validação de BIN durante a triagem de pedidos suspeitos) enquanto mantém o mesmo método HTTP, URL e parâmetros documentados neste post.
Colocando tudo junto
Em um fluxo típico de backend:
- O cliente coleta a entrada do cartão e envia apenas o BIN (primeiros 6 dígitos) para seu servidor.
- Seu servidor solicita GET /check-card com bin=XXXXXX e Authorization: Bearer YOUR_API_KEY.
- Se success e isValid forem verdadeiros, use data.card_brand, data.card_type e país do emissor para aplicar regras de roteamento ou risco.
- Armazene a resposta em cache por BIN para evitar consultas repetidas.
- Prossiga com sua tentativa de pagamento ou escale para 3DS/desafio com base nas regras que você definiu.
Lista de verificação de solução de problemas
- 401 ou problema de autenticação semelhante: Confirme que seu cabeçalho Authorization é exatamente Authorization: Bearer YOUR_API_KEY e que a chave está ativa.
- Nenhum campo em data: Certifique-se de que o parâmetro bin está presente e tem exatamente 6 dígitos.
- Erros inesperados: Registre o corpo JSON completo e os cabeçalhos relevantes (excluindo segredos) para diagnóstico; tente novamente de forma responsável a partir de uma fila para evitar bloquear o checkout.
- Emissor diferente do esperado: Bancos de dados de emissores evoluem; atualize seu cache e verifique novamente a resposta mais recente para o BIN.
FAQ
Como é um BIN válido?
Um BIN válido tem exatamente 6 dígitos. Remova quaisquer espaços ou separadores da entrada do usuário antes de enviar o bin.
Preciso enviar um número de cartão completo?
Não. Envie apenas o BIN de 6 dígitos no parâmetro de consulta bin.
Como faço para autenticar?
Inclua um cabeçalho Authorization com o valor Bearer YOUR_API_KEY em cada solicitação.
Como é tratado o faturamento?
APIs no Zyla usam um modelo de assinatura + cota (não paga por chamada). A primeira API que você tenta inclui um teste de 7 dias ou 50 solicitações. Verifique a página da API para opções de acesso e preços atuais.
Posso chamar isso de um agente de IA?
Sim. Use um cliente compatível com MCP apontando para o endpoint MCP e certifique-se de que o cabeçalho Authorization esteja definido quando seu agente fizer a chamada GET.
Pronto para validar e enriquecer os BINs de cartões em sua pilha financeira? Inscreva-se e obtenha sua chave na lista da API Card Checker: Iniciar teste de 7 dias na API Card Checker. Cole o cURL acima em seu terminal, confirme isValid e implemente sua integração.
