API de Verificación de Tarjetas en Zyla API Hub: Primera Solicitud con curl y JSON

Necesitas verificar el BIN/IIN de una tarjeta de pago antes de enviar un flujo de pago, bloquear tarjetas no soportadas o enrutar transacciones. Al final de esta guía, harás una solicitud GET funcional a la API de Verificación de Tarjetas en Zyla API Hub, analizarás la respuesta y la integrarás en tu servicio usando curl, Python o JavaScript, listo para desplegar esta semana.

Qué devuelve la API y cuándo usarla

La API de Verificación de Tarjetas valida un BIN/IIN (los primeros 6 dígitos de un número de tarjeta) y devuelve metadatos estructurados sobre la tarjeta, incluyendo marca, tipo, nivel, emisor, detalles de contacto del emisor y país. Los usos típicos incluyen:

Ilustración: API de Verificación de Tarjetas en Zyla API Hub: Primera Solicitud con curl y JSON

Pre-validar BINs en el pago para mostrar la marca y el emisor de inmediato.
Bloquear marcas o países no soportados del lado del servidor antes de la autorización.
Logística de enrutamiento: por ejemplo, enviar MASTERCARD CRÉDITO ORO emitido en TR a un procesador específico.
Analítica: segmentar conversiones por emisor o país sin manejar PANs completos.

Todas las llamadas pasan por Zyla API Hub, así que usas una cuenta, una clave API y un único modelo de suscripción a través de las APIs.

Comenzando en Zyla API Hub

Para llamar a la API de Verificación de Tarjetas, ve a su página de listado y suscríbete: API de Verificación de Tarjetas en Zyla API Hub. Haz clic en Suscribirse (o Comenzar Prueba Gratuita si está disponible). En Zyla, la facturación es suscripción + cuota (no pago por llamada). Para tu primera API, normalmente obtienes una prueba de 7 días o 50 solicitudes; no hay Plan Gratuito. Consulta la página de la API para las opciones de acceso y precios actuales. Después de suscribirte, recibirás una clave API. Úsala en el encabezado de Autorización como:

Authorization: Bearer YOUR_API_KEY

Si aún no tienes una cuenta, crea una aquí: Registrarse.

Descripción general del endpoint

La API de Verificación de Tarjetas expone un único endpoint que valida un BIN y devuelve detalles de la tarjeta y del emisor.

Nombre: Verificar tarjeta
Método: GET
URL: https://zylalabs.com/api/2333/card-checker-api/2243/check-card
Parámetro de consulta requerido:
- bin (número): Los primeros 6 dígitos de la tarjeta. Ejemplo: 444444

Comportamiento de alto nivel: proporcionas un BIN de 6 dígitos y recibes un booleano de validación, un mensaje y un objeto de datos con marca, tipo, nivel, emisor, información de contacto del emisor y país ISO.

Primera solicitud con curl

Haz tu primera llamada con el ejemplo oficial. Reemplaza YOUR_API_KEY con tu token de Zyla.

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

Respuesta JSON de muestra 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 clave que utilizarás:

isValid: Booleano que indica si el BIN es reconocido como válido.
card_brand, card_type, card_level: Clasificación de la tarjeta para UI y lógica de enrutamiento.
issuer_name_bank, issuer_bank_phone, issuer_bank_website: Metadatos del emisor para flujos de soporte o verificaciones de cumplimiento.
iso_country_name, iso_country_code: País (código ISO alfa-2) para lógica geográfica.

Ejemplo de Python: validar y ramificar por marca

El fragmento a continuación llama al mismo endpoint y ramifica la lógica para una marca y país específicos. Utiliza solo el parámetro y encabezado 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")
type = details.get("card_type")
level = details.get("card_level")
country = details.get("iso_country_code")

print(f"Marca={brand}, Tipo={type}, Nivel={level}, País={country}")

# Ejemplo de condición de enrutamiento
if brand == "MASTERCARD" and type == "CREDIT" and country == "TR":
print("Enrutar al procesador: TR-MC-CREDIT")
else:
print("Enrutar al procesador predeterminado")
else:
print("BIN no válido o búsqueda no exitosa")

Para probar localmente, exporta ZYLALABS_API_KEY y ejecuta el script. Los tiempos de espera, reintentos y registros quedan a tu entorno.

Ejemplo de JavaScript: entorno edge o Node

Este ejemplo utiliza fetch para llamar al mismo endpoint y lee los campos prácticos para una UI de pago.

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(`Marca: ${card_brand}, Tipo: ${card_type}, Nivel: ${card_level}`);
console.log(`Emisor: ${issuer_name_bank}, País: ${iso_country_code}`);
} else {
console.log("BIN inválido o búsqueda fallida");
}
}

checkBin().catch(err => {
console.error("La solicitud falló:", err);
});

Usa el mismo código en trabajos sin servidor, edge o en segundo plano. Mantén la clave API del lado del servidor y nunca la expongas a los navegadores.

Respuestas de muestra que puedes almacenar para pruebas locales

Al construir flujos de UI y pruebas unitarias, guarda algunos archivos de fixture con la respuesta de muestra oficial para que puedas iterar sin alcanzar cuotas. Aquí está la muestra JSON oficial nuevamente:

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

También puedes duplicar el mismo JSON bajo diferentes nombres de archivo (por ejemplo, sample_valid_1.json, sample_valid_2.json) para ejercitar consistentemente los caminos del analizador a través de los servicios.

{
"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 pruebas de extremo a extremo, carga el mismo fixture y verifica que tu aplicación mapea marca/tipo/nivel a la elección de UX o enrutamiento 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"
}
}

Detalles de implementación que ahorran tiempo

Validación de parámetros: Acepta estrictamente 6 dígitos numéricos para el parámetro bin del lado del servidor. Rechaza cualquier otra cosa antes de llamar a la API.
Cacheo: Los metadatos del BIN no son específicos del usuario. Almacena en caché las respuestas exitosas por BIN en tu almacén de datos o caché de edge para reducir los viajes de ida y vuelta.
Tiempos de espera y reintentos: Establece un tiempo de espera explícito en tu cliente HTTP. Usa reintentos conservadores con retroceso solo en categorías seguras para reintentar en tu entorno.
Alcance PCI: Solo transmites un BIN (los primeros 6 dígitos), no un PAN completo. Mantén la llamada del lado del servidor y evita registrar claves API o encabezados sensibles.
Internacionalización: Usa iso_country_code para localizar insignias de UI, reglas de fraude o políticas de enrutamiento.
Analítica: Persiste {card_brand, card_type, card_level, iso_country_code} para agrupar conversiones, rechazos y contracargos por cohorte.

Mapeo de la respuesta a la lógica de la aplicación

Aquí hay un patrón de mapeo sencillo que puedes adaptar a tu stack:

Al ingresar el BIN (primeros 6 dígitos), emite una llamada del lado del servidor al endpoint con bin.
Si isValid y success son ambos verdaderos:
- Muestra el ícono de la marca usando card_brand (por ejemplo, MASTERCARD).
- Selecciona la ruta de procesamiento usando card_type y iso_country_code.
- Habilita reglas 3DS o SCA específicas del país si son aplicables en tu sistema.
Si la validación falla (por ejemplo, no success o no isValid), procede con una UX genérica o muestra una pista no bloqueante.

Mantén el issuer_name_bank disponible para registros de soporte o flujos de disputas.

Llamando a la API desde agentes de IA a través de MCP

Si orquestas tareas de desarrollo con clientes compatibles con MCP (Claude Code, Cursor, Windsurf, etc.), también puedes invocar las APIs de Zyla a través del endpoint MCP. Proporciona tu clave API de Zyla como lo indica tu cliente y llama:

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

Revisa la documentación de MCP y conecta tu cliente para que tu agente pueda hacer la misma solicitud GET al endpoint de la API de Verificación de Tarjetas y devolver el JSON a tu espacio de trabajo. Aprende más aquí: MCP.

Notas operativas

Cuotas y prueba: Zyla utiliza suscripción + cuota. Para tu primera API, normalmente obtienes una prueba de 7 días o 50 solicitudes. No hay Plan Gratuito. Consulta la página de la API de Verificación de Tarjetas para detalles actuales.
Seguridad: Mantén los encabezados de Autorización del lado del servidor. Rota tu clave si se expone.
Observabilidad: Registra los ID de solicitud en tu sistema. Redacta las claves API y evita almacenar PANs completos en cualquier registro interno.
Degradación elegante: Si la búsqueda no está temporalmente disponible en tu entorno, permite que el pago continúe con un texto genérico (no bloquees a usuarios legítimos en una búsqueda de metadatos transitoria).

Otra mirada al JSON oficial para claridad de contrato

Para traspasos de equipo e integración primero por contrato, mantén la muestra oficial en tu documentación para aclarar nombres de campos y anidación:

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

Usa estas claves exactas en tus serializadores, DTOs o tipos de TypeScript para evitar desajustes entre servicios.

Lista de verificación de solución de problemas

Errores 401/403 en tu entorno: Asegúrate de que el encabezado de Autorización esté presente y que la clave esté activa bajo tu cuenta de Zyla.
Forma JSON inesperada en tu analizador: Revisa que estés llamando a la URL del endpoint documentado y solo pasando el parámetro bin.
BINS que parecen válidos pero devuelven no isValid en tu UI: Verifica que estés enviando exactamente 6 dígitos y no eliminando ceros a la izquierda durante el análisis numérico.
Errores de red intermitentes en sin servidor: Aumenta ligeramente el tiempo de espera y agrega un reintento con jitter; almacena en caché búsquedas exitosas anteriores.

¿A dónde ir a continuación?

Explora la lista de la API de Verificación de Tarjetas para opciones de suscripción, cuotas y orientación de uso: API de Verificación de Tarjetas. Zyla centraliza la autenticación, facturación y monitoreo a través de miles de APIs, así que una vez que esto esté en vivo, es sencillo agregar otras APIs de pagos o enriquecimiento de datos bajo la misma clave en Zyla.

FAQ

¿Cuál es la URL exacta y el método para la verificación del BIN?
GET https://zylalabs.com/api/2333/card-checker-api/2243/check-card con el parámetro de consulta bin y Authorization: Bearer YOUR_API_KEY.

¿Qué parámetros son requeridos?
bin (número, 6 dígitos). Ejemplo: 444444. No se requieren otros parámetros para este endpoint.

¿Qué campos debo consumir de la respuesta?
Verifica success y isValid primero. Luego lee data.card_brand, data.card_type, data.card_level, data.issuer_name_bank, data.iso_country_code (y iso_country_name si lo muestras).

¿Cómo se maneja la facturación?
Zyla utiliza suscripción + cuota (no pago por llamada). Para tu primera API, normalmente obtienes una prueba de 7 días o 50 solicitudes. No hay Plan Gratuito. Consulta la página de la API para detalles actuales.

¿Puedo llamar a esto desde agentes de codificación de IA?
Sí, a través del endpoint MCP de Zyla en https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY. Configura tu cliente compatible con MCP para emitir la misma llamada GET y devolver el JSON.

¿Listo para enviar tu integración? Crea tu cuenta, suscríbete a la API de Verificación de Tarjetas y obtén tu clave aquí: Registrarse. Luego usa el comando curl anterior para verificar tu primer BIN e integrar la respuesta en tu lógica de pago o enrutamiento.