API para verificação de BIN

Você precisa validar os BINs dos cartões esta semana para que seu checkout, KYC ou motor de risco possam decidir como roteirizar, sinalizar ou enriquecer transações. Ao final deste artigo, você chamará uma API de Finanças pronta para produção para verificar um BIN de 6 dígitos e ler de volta os metadados da marca do cartão, tipo e emissor que você pode integrar diretamente em seus fluxos.

O que esta API retorna e por que os desenvolvedores a utilizam

A API de Validação de Cartão de Crédito - Verificador de BIN no Zyla API Hub retorna detalhes sobre um cartão de pagamento com base em seu BIN (os primeiros 6 dígitos). Você pode confirmar se o BIN é válido e ler campos incluindo card_brand, card_type, card_level, metadados do emissor e campos de país ISO.

Casos de uso típicos de Finanças:

Fluxos de checkout: determine a marca e o tipo do cartão cedo para otimizar a experiência do usuário (por exemplo, exibir o logotipo da marca, ajustar máscaras de campo).
Fraude/risco: bloquear ou revisar transações com base no país do emissor ou tipos não suportados.
Roteamento: escolha um adquirente ou meio de pagamento dependendo da marca ou tipo.
Analytics: segmentar transações por marca/tipo para relatórios.

Você acessará esta API através do Zyla API Hub, que fornece uma única conta e chave em mais de 10.000 APIs públicas. A autenticação é a mesma em todo o mercado, o que simplifica sua integração e manutenção.

Começando no Zyla API Hub

Abra a listagem do marketplace para a API da categoria Finanças que estamos usando aqui e inscreva-se. Você obtém uso através de assinatura e cota (não pago por chamada). A primeira API que você conectar pode começar com um teste de 7 dias ou 50 solicitações; verifique a página do item para as opções de acesso atuais.

Vá para a página da API: Iniciar teste de 7 dias na API de Validador de Cartão de Crédito - Verificador de BIN
Clique em Inscrever-se ou Iniciar Teste Gratuito quando disponível, e então obtenha sua chave de API.
Use sua chave com o cabeçalho Authorization: Bearer YOUR_API_KEY em cada solicitação.

Você pode navegar por mais APIs de Finanças e outras categorias no Zyla API Hub, e reutilizar a mesma chave e modelo de assinatura em todo o mercado.

Referência de endpoint e início rápido com cURL

Abaixo está o único endpoint que você precisa para validação e enriquecimento de BIN. Apenas os parâmetros explicitamente listados são suportados aqui; não adicione outros.

Endpoint: Verificador de BIN
Método: GET
URL de solicitação: https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker
Parâmetro de consulta obrigatório:
- bin (string): Número de Identificação Bancária de 6 dígitos

Autenticação:

Cabeçalho: Authorization: Bearer YOUR_API_KEY

Exemplo oficial de cURL (copie/cole para verificar sua configuração):

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"

Resposta JSON oficial (os campos que você irá analisar são mostrados abaixo exatamente como retornados):

{
"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 que você provavelmente consumirá:

isValid: porta boolean para aceitar ou ramificar lógica para BINs desconhecidos/inválidos.
data.card_brand: exibir ou roteirizar por marca (por exemplo, AMERICAN EXPRESS).
data.card_type: diferenças de manuseio entre CRÉDITO ou DÉBITO (por exemplo, regras de sobretaxa, roteamento).
data.bin_iin: eco do BIN de entrada (para registro e análise).
Campos do emissor e ISO: enriquecimento opcional; apresentados como strings ou nulo.

Chamando de agentes de IA via MCP

Se você preferir orquestrar chamadas com um agente de IA em um IDE ou cliente compatível, a Zyla expõe APIs do marketplace através de seu endpoint MCP. Configure seu cliente compatível com MCP e aponte-o para MCP. Use sua chave de API Zyla com o parâmetro de consulta apikey para o endpoint MCP (ou seja, apikey=YOUR_API_KEY). Na solicitação da sua ferramenta, direcione para a mesma URL GET do Verificador de BIN e passe a string de consulta bin como mostrado acima. O corpo da resposta e os campos permanecem os mesmos que a chamada HTTP direta.

Exemplo em Python: validar um BIN e ramificar seu fluxo

Este trecho mínimo de Python chama o endpoint exato acima, lê isValid, e então ramifica com base em card_brand e card_type. Ele foi escrito para ser copiado e colado em uma ferramenta CLI ou serviço de backend para uso imediato.

import os
import requests

API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
URL = "https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker"
params = {"bin": "346350"}
headers = {"Authorization": f"Bearer {API_KEY}"}

resp = requests.get(URL, params=params, headers=headers, timeout=15)
resp.raise_for_status()
data = resp.json()

# Verificações rápidas
if not data.get("success"):
raise RuntimeError(f"A solicitação não foi bem-sucedida: {data}")

if not data.get("isValid"):
print("BIN inválido ou desconhecido. Aplique fallback ou bloqueie.")
else:
info = data.get("data", {})
brand = info.get("card_brand")
ctype = info.get("card_type")
issuer = info.get("issuer_name_bank")
iso_code = info.get("iso_country_code")

# Lógica de roteamento de exemplo
if brand == "AMERICAN EXPRESS":
print("Roteie para adquirente compatível com AMEX.")
elif brand in ("VISA", "MASTERCARD"):
print("Roteie para adquirente mainstream A.")
else:
print("Use adquirente padrão B.")

# Exemplo de verificações de conformidade/risco
if ctype == "CREDIT":
print("Aplique lógica de sobretaxa de cartão de crédito, se aplicável.")
if iso_code is None:
print("País do emissor desconhecido; considere verificações adicionais.")

# Registre ou emita um evento estruturado
result = {
"bin": info.get("bin_iin"),
"brand": brand,
"type": ctype,
"issuer": issuer,
"iso_country_code": iso_code,
}
print("Resultado da pesquisa de BIN:", result)

Notas para produção:

Timeouts: 10–20 segundos é razoável para variabilidade de rede; ajuste para seu SLO.
Cache: os dados do BIN são relativamente estáveis; armazene em cache por BIN de 6 dígitos por horas ou dias para reduzir latência e chamadas.
Retries: implemente tentativas idempotentes com backoff em erros HTTP transitórios.
PII: um BIN não é PII em nível de PAN, mas ainda trate os logs com cuidado; nunca registre números de cartão completos.

Exemplos de resposta que você pode testar e analisar

Todos os exemplos abaixo demonstram a forma oficial da resposta. Você pode confiar nesses nomes de campo em sua lógica de análise.

Exemplo A

{
"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 B (mesma estrutura; valide se sua análise JSON é robusta a nulos)

{
"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 C (use em testes unitários para fixar nomes e tipos de campos)

{
"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 D (focado em esquema: leia as flags de nível superior antes de aprofundar nos dados)

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

Implementações práticas em Finanças

Conecte o Verificador de BIN aos fluxos de pagamento principais para reduzir recusas e melhorar a tomada de decisões:

UX de checkout: após um usuário digitar o 6º dígito, acesse o endpoint para determinar card_brand e exibir o logotipo relevante ou atualizar máscaras de entrada para AMERICAN EXPRESS vs outros.
Filtros de risco: se isValid for falso, bloqueie ou solicite um método alternativo antes de enviar ao seu processador.
Estratégias de roteamento: para card_type == CREDIT, envie para um adquirente com otimização de intercâmbio favorável; para DEBIT (quando aplicável), roteie de forma diferente ou solicite opções de PIN se relevante para sua pilha.
Conformidade: leia iso_country_code para informar restrições geográficas ou verificação adicional onde a região do emissor importa.
Ferramentas de suporte ao cliente: mostre metadados do BIN em seu visualizador de pedidos interno para que os agentes possam entender rapidamente o contexto do cartão.

Detalhes de engenharia que economizam tempo:

Chame a API apenas quando você tiver exatamente 6 dígitos. Não chame a cada pressionamento de tecla.
Armazene em cache na chave do BIN; evite duplicação por usuário. Mesmo um cache LRU simples pode reduzir dramaticamente a latência e o uso.
Superfície de mensagem para painéis de operadores. É amigável para humanos e ajuda na depuração.
Registre os campos de status e sucesso. Eles são úteis para distinguir problemas de transporte de validação de domínio.
Coordene flags de recursos para que você possa falhar aberto ou fechado se o serviço de BIN estiver indisponível, de acordo com sua postura de risco.

Precisa de mais blocos de construção de Finanças? Explore categorias e listagens adicionais no Zyla API Hub e reutilize a mesma chave do marketplace.

FAQ

Qual é a entrada mínima necessária?
Você deve fornecer um BIN de 6 dígitos usando o parâmetro de consulta bin para o endpoint GET do Verificador de BIN.

Como faço para autenticar?
Inclua o cabeçalho Authorization: Bearer YOUR_API_KEY em cada solicitação que você enviar para o endpoint do Zyla API Hub.

O preço é pago por chamada?
Não. As APIs da Zyla usam assinatura com cota. Verifique a página do item do marketplace para as opções de acesso e preços atuais.

Há um plano gratuito?
Não há Plano Gratuito. Para sua primeira API, você pode começar com um teste de 7 dias ou 50 solicitações quando disponível; veja a listagem para detalhes.

Posso chamar isso de um agente ou assistente de IDE?
Sim. Use a integração MCP da Zyla com sua chave. Configure seu cliente compatível com MCP para acessar o mesmo endpoint do Verificador de BIN e passe bin como mostrado acima.

Pronto para validar BINs em produção? Inscreva-se no marketplace e comece sua integração agora: Iniciar teste de 7 dias na API de Validador de Cartão de Crédito - Verificador de BIN.