API de Verificação de Cartão no Zyla API Hub: Primeiro Pedido com curl e JSON

Você precisa verificar o BIN/IIN de um cartão de pagamento antes de enviar um fluxo de checkout, bloquear cartões não suportados ou direcionar transações. Ao final deste guia, você fará uma solicitação GET funcional para a API de Verificação de Cartão no Zyla API Hub, analisará a resposta e integrará ao seu serviço usando curl, Python ou JavaScript—pronto para ser implantado esta semana.

O que a API retorna e quando usá-la

A API de Verificação de Cartão valida um BIN/IIN (os primeiros 6 dígitos de um número de cartão) e retorna metadados estruturados sobre o cartão, incluindo marca, tipo, nível, emissor, detalhes de contato do emissor e país. Usos típicos incluem:

Ilustração: API de Verificação de Cartão no Zyla API Hub: Primeiro Pedido com curl e JSON

Pré-validação de BINs no checkout para mostrar a marca e o emissor imediatamente.
Bloqueio de marcas ou países não suportados no servidor antes da autorização.
Lógica de roteamento: por exemplo, enviar MASTERCARD CRÉDITO OURO emitido na TR para um processador específico.
Análise: segmentar conversões por emissor ou país sem lidar com PANs completos.

Todos os chamados passam pelo Zyla API Hub, então você usa uma conta, uma chave de API e um único modelo de assinatura em todas as APIs.

Começando no Zyla API Hub

Para chamar a API de Verificação de Cartão, vá para sua página de listagem e inscreva-se: API de Verificação de Cartão no Zyla API Hub. Clique em Inscrever-se (ou Começar Teste Gratuito, se disponível). No Zyla, a cobrança é por assinatura + cota (não é pago por chamada). Para sua primeira API, você normalmente recebe um teste de 7 dias ou 50 solicitações; não há Plano Gratuito. Verifique a página da API para opções de acesso e preços atuais. Após se inscrever, você receberá uma chave de API. Use-a no cabeçalho de Autorização como:

Authorization: Bearer YOUR_API_KEY

Se você ainda não tem uma conta, crie uma aqui: Registrar.

Visão geral do endpoint

A API de Verificação de Cartão expõe um único endpoint que valida um BIN e retorna detalhes do cartão e do emissor.

Nome: 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

Comportamento de alto nível: você fornece um BIN de 6 dígitos e recebe um booleano de validação, mensagem e um objeto de dados com marca, tipo, nível, emissor, informações de contato do emissor e país ISO.

Primeira solicitação com curl

Faça sua primeira chamada com o exemplo oficial. Substitua YOUR_API_KEY pelo seu token do Zyla.

curl -s -X GET "https://zylalabs.com/api/2333/card-checker-api/2243/check-card?bin=444444" \
-H "Authorization: Bearer YOUR_API_KEY"

Resposta JSON de exemplo oficial:

{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"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": "TURKEY",
"iso_country_code": "TR"
}
}

Campos principais que você usará:

isValid: Booleano indicando se o BIN é reconhecido como válido.
card_brand, card_type, card_level: Classificação do cartão para UI e lógica de roteamento.
issuer_name_bank, issuer_bank_phone, issuer_bank_website: Metadados do emissor para fluxos de suporte ou verificações de conformidade.
iso_country_name, iso_country_code: País (código ISO alpha-2) para lógica baseada em geolocalização.

Exemplo em Python: validar e ramificar por marca

O trecho abaixo chama o mesmo endpoint e ramifica a lógica para uma marca e país específicos. Ele usa apenas o parâmetro e cabeçalho documentados.

import os
import requests

API_KEY = os.environ.get("ZYLALABS_API_KEY", "YOUR_API_KEY")
URL = "https://zylalabs.com/api/2333/card-checker-api/2243/check-card"
params = {"bin": 444444}
headers = {"Authorization": f"Bearer {API_KEY}"}

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

if data.get("success") and data.get("isValid") and data.get("data"):
details = data["data"]
brand = details.get("card_brand")
ctype = details.get("card_type")
level = details.get("card_level")
country = details.get("iso_country_code")

print(f"Brand={brand}, Type={ctype}, Level={level}, Country={country}")

# Exemplo de condição de roteamento
if brand == "MASTERCARD" and ctype == "CREDIT" and country == "TR":
print("Roteie para o processador: TR-MC-CREDIT")
else:
print("Roteie para o processador padrão")
else:
print("BIN não válido ou pesquisa malsucedida")

Para testar localmente, exporte ZYLALABS_API_KEY e execute o script. Timeouts, tentativas e registro são deixados para o seu ambiente.

Exemplo em JavaScript: edge ou runtime Node

Este exemplo usa fetch para chamar o mesmo endpoint e lê os campos práticos para uma UI de checkout.

const API_KEY = process.env.ZYLALABS_API_KEY || "YOUR_API_KEY";
const url = "https://zylalabs.com/api/2333/card-checker-api/2243/check-card?bin=444444";

async function checkBin() {
const res = await fetch(url, {
method: "GET",
headers: { "Authorization": `Bearer ${API_KEY}` }
});
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
const json = await res.json();

if (json.success && json.isValid && json.data) {
const {
card_brand,
card_type,
card_level,
issuer_name_bank,
iso_country_code
} = json.data;

console.log(`Brand: ${card_brand}, Type: ${card_type}, Level: ${card_level}`);
console.log(`Issuer: ${issuer_name_bank}, Country: ${iso_country_code}`);
} else {
console.log("BIN inválido ou pesquisa falhou");
}
}

checkBin().catch(err => {
console.error("Solicitação falhou:", err);
});

Use o mesmo código em funções sem servidor, edge ou trabalhos em segundo plano. Mantenha a chave da API no lado do servidor e nunca a exponha a navegadores.

Respostas de exemplo que você pode armazenar para testes locais

Ao construir fluxos de UI e testes unitários, mantenha alguns arquivos de fixture com a resposta de exemplo oficial para que você possa iterar sem atingir cotas. Aqui está a resposta JSON de exemplo oficial novamente:

{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"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": "TURKEY",
"iso_country_code": "TR"
}
}

Você também pode duplicar o mesmo JSON sob nomes de arquivos diferentes (por exemplo, sample_valid_1.json, sample_valid_2.json) para exercitar caminhos de analisador de forma consistente entre serviços.

{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"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": "TURKEY",
"iso_country_code": "TR"
}
}

Para testes de ponta a ponta, carregue a mesma fixture e afirme que sua aplicação mapeia marca/tipo/nível para a escolha de UX ou roteamento esperada.

{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"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": "TURKEY",
"iso_country_code": "TR"
}
}

Detalhes de implementação que economizam tempo

Validação de parâmetros: Aceite estritamente 6 dígitos numéricos para o parâmetro bin no servidor. Rejeite qualquer outra coisa antes de chamar a API.
Cache: Metadados do BIN não são específicos do usuário. Armazene em cache respostas bem-sucedidas por BIN em seu armazenamento de dados ou cache de edge para reduzir viagens de ida e volta.
Timeouts e tentativas: Defina um timeout explícito em seu cliente HTTP. Use tentativas conservadoras com backoff apenas em categorias seguras para tentar novamente em seu ambiente.
Escopo PCI: Você só transmite um BIN (primeiros 6 dígitos), não um PAN completo. Mantenha a chamada no lado do servidor e evite registrar chaves de API ou cabeçalhos sensíveis.
Internacionalização: Use iso_country_code para localizar distintivos de UI, regras de fraude ou políticas de roteamento.
Análise: Persista {card_brand, card_type, card_level, iso_country_code} para agrupar conversões, recusas e chargebacks por coorte.

Mapeando a resposta para a lógica da aplicação

Aqui está um padrão de mapeamento direto que você pode adaptar para sua pilha:

Na entrada do BIN (primeiros 6 dígitos), emita uma chamada no servidor para o endpoint com bin.
Se isValid e success forem ambos verdadeiros:
- Mostre o ícone da marca usando card_brand (por exemplo, MASTERCARD).
- Selecione a rota de processamento usando card_type e iso_country_code.
- Ative regras específicas de país para 3DS ou SCA, se aplicável em seu sistema.
Se a validação falhar (por exemplo, não success ou não isValid), prossiga com UX genérica ou exiba uma dica não bloqueadora.

Mantenha issuer_name_bank disponível para registros de suporte ou fluxos de disputas.

Chamando a API de agentes de IA via MCP

Se você orquestra tarefas de desenvolvimento com clientes compatíveis com MCP (Claude Code, Cursor, Windsurf, etc.), você também pode invocar APIs Zyla através do endpoint MCP. Forneça sua chave de API Zyla conforme indicado pelo seu cliente e chame:

Base MCP: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY

Revise a documentação do MCP e conecte seu cliente para que seu agente possa fazer a mesma solicitação GET para o endpoint da API de Verificação de Cartão e retornar o JSON para seu espaço de trabalho. Saiba mais aqui: MCP.

Notas operacionais

Cotas e teste: Zyla usa assinatura + cota. Para sua primeira API, você normalmente recebe um teste de 7 dias ou 50 solicitações. Não há Plano Gratuito. Verifique a página da API de Verificação de Cartão para detalhes atuais.
Segurança: Mantenha os cabeçalhos de Autorização no lado do servidor. Rode sua chave se exposta.
Observabilidade: Registre IDs de solicitação em seu sistema. Reduza chaves de API e evite armazenar PANs completos em quaisquer registros internos.
Degradação graciosa: Se a pesquisa estiver temporariamente indisponível em seu ambiente, permita que o checkout prossiga com cópia genérica (não bloqueie usuários legítimos em uma pesquisa de metadados transitória).

Outra olhada no JSON oficial para clareza de contrato

Para transferências de equipe e integração primeiro com contrato, mantenha o exemplo oficial em sua documentação para esclarecer nomes de campos e aninhamento:

{
"status": 200,
"success": true,
"isValid": true,
"message": "The BIN number is valid.",
"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": "TURKEY",
"iso_country_code": "TR"
}
}

Use essas chaves exatas em seus serializadores, DTOs ou tipos TypeScript para evitar incompatibilidades entre serviços.

Lista de verificação de solução de problemas

Erros 401/403 em seu ambiente: Certifique-se de que o cabeçalho de Autorização está presente e a chave está ativa sob sua conta Zyla.
Forma JSON inesperada em seu analisador: Verifique novamente se você está chamando a URL do endpoint documentado e passando apenas o parâmetro bin.
BINs que parecem válidos, mas retornam não isValid em sua UI: Verifique se você está enviando exatamente 6 dígitos e não removendo zeros à esquerda durante a análise numérica.
Erros de rede intermitentes em sem servidor: Aumente o timeout ligeiramente e adicione uma tentativa com jitter; armazene em cache pesquisas bem-sucedidas anteriores.

Para onde ir a seguir

Explore a listagem da API de Verificação de Cartão para opções de assinatura, cotas e orientações de uso: API de Verificação de Cartão. O Zyla centraliza autenticação, cobrança e monitoramento em milhares de APIs, então uma vez que isso esteja ativo, é simples adicionar outras APIs de pagamentos ou enriquecimento de dados sob a mesma chave no Zyla.

FAQ

Qual é a URL exata e o método para a verificação do BIN?
GET https://zylalabs.com/api/2333/card-checker-api/2243/check-card com o parâmetro de consulta bin e Authorization: Bearer YOUR_API_KEY.

Quais parâmetros são obrigatórios?
bin (número, 6 dígitos). Exemplo: 444444. Nenhum outro parâmetro é necessário para este endpoint.

Quais campos devo consumir da resposta?
Verifique success e isValid primeiro. Depois leia data.card_brand, data.card_type, data.card_level, data.issuer_name_bank, data.iso_country_code (e iso_country_name se você exibi-lo).

Como a cobrança é tratada?
Zyla usa assinatura + cota (não pago por chamada). Para sua primeira API, você normalmente recebe um teste de 7 dias ou 50 solicitações. Não há Plano Gratuito. Veja a página da API para detalhes atuais.

Posso chamar isso de agentes de codificação de IA?
Sim, via endpoint MCP do Zyla em https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY. Configure seu cliente compatível com MCP para emitir a mesma chamada GET e retornar o JSON.

Pronto para enviar sua integração? Crie sua conta, inscreva-se na API de Verificação de Cartão e obtenha sua chave aqui: Registrar. Em seguida, use o comando curl acima para verificar seu primeiro BIN e integrar a resposta em sua lógica de checkout ou roteamento.