Tienes datos de tarjetas de crédito fluyendo en tu proceso de pago, flujo de KYC o sistema de riesgo, y necesitas una forma rápida de validar el BIN (primeros 6 dígitos) e identificar la marca, tipo y metadatos del emisor—esta semana, no el próximo trimestre. Al final de este artículo, podrás validar un BIN y recuperar información sobre la marca de la tarjeta, tipo y emisor utilizando el validador de tarjetas de crédito - API de verificación de BIN en Zyla API Hub—completo con cURL y Python para copiar y pegar.
Qué hace esta API y por qué es importante
La API de verificación de BIN del validador de tarjetas de crédito devuelve metadatos para un BIN dado (los primeros 6 dígitos de un número de tarjeta). Con una sola solicitud GET, aprenderás si el BIN es válido y obtendrás datos como:
- Marca de la tarjeta (por ejemplo, AMERICAN EXPRESS)
- Tipo de tarjeta (por ejemplo, CRÉDITO)
- Nivel de tarjeta cuando esté disponible
- Datos del emisor (cuando estén disponibles)
- Información del país (cuando esté disponible)
Los equipos utilizan las verificaciones de BIN para pre-validar entradas, seleccionar automáticamente elementos de la interfaz de usuario de la marca de la tarjeta, aplicar reglas adicionales de fraude y enrutar pagos. Dado que la solicitud utiliza solo los primeros 6 dígitos, reduce el alcance de PCI en comparación con el envío de PANs completos.
Esta API es parte de la categoría Finanzas & Pagos en Zyla API Hub, un mercado con más de 10,000 APIs públicas bajo una cuenta, una clave API y un modelo de suscripción. Puedes gestionar tu uso en un solo lugar y llamar a múltiples APIs a medida que tu stack crece.
Comenzando en Zyla API Hub
Para probar la API de verificación de BIN del validador de tarjetas de crédito:
- Abre la lista de APIs: Iniciar prueba de 7 días en la API de verificación de BIN del validador de tarjetas de crédito.
- Haz clic en Suscribirse o Iniciar prueba gratuita (cuando esté disponible). Esta API generalmente admite una prueba de 7 días para ayudarte a construir y probar rápidamente. Consulta la página de la API para las opciones de acceso y precios actuales.
- Copia tu clave API desde tu panel de control.
Todas las solicitudes utilizan un token Bearer en el encabezado de Autorización. La facturación es por suscripción + cuota (no por llamada). No hay un plan gratuito; utiliza la prueba para evaluar. Mantén tu clave segura; no la incrustes en código de front-end público.
Descripción general del endpoint
Esta API expone un endpoint GET para la validación de BIN y metadatos:
- Método: GET
- URL: https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker
- Parámetro de consulta:
- bin (cadena, requerido): Primeros 6 dígitos de la tarjeta (BIN/IIN). Ejemplo: 346350
- Autenticación: Autorización: Bearer YOUR_API_KEY
Comportamiento de alto nivel: Envías un BIN, y la API responde con un código de estado, una bandera de éxito, un campo booleano isValid, un mensaje y un objeto de datos que contiene metadatos de la tarjeta. Si algunos atributos no están disponibles, la respuesta reflejará eso con marcadores de posición o nulos.
cURL que puedes copiar/pegar
Aquí hay un ejemplo completo y funcional contra el endpoint en vivo. Reemplaza YOUR_API_KEY con tu clave de Zyla API Hub:
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"Respuesta de ejemplo oficial
Este es el payload de muestra oficial devuelto por el endpoint al consultar el BIN 346350:
{
"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 sobre los campos que probablemente usarás:
- status: Código de estado numérico similar a HTTP devuelto por el servicio.
- success: Indica que la solicitud fue procesada con éxito.
- isValid: Verdadero si el BIN existe y es reconocido.
- message: Resumen de validación legible por humanos.
- data: Metadatos de la tarjeta, donde cualquier información faltante o restringida puede ser devuelta como marcadores de posición o nulos.
Ejemplo en Python: llamando al endpoint y analizando campos
Este script envía un BIN, verifica la validez e imprime atributos seleccionados para la lógica de enrutamiento o visualización.
import os
import requests
API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
BIN = "346350"
url = "https://zylalabs.com/api/40/credit-card-validator-bin-checker-api/1885/bin-checker"
params = {"bin": BIN}
headers = {
"Authorization": f"Bearer {API_KEY}"
}
resp = requests.get(url, params=params, headers=headers, timeout=10)
resp.raise_for_status()
data = resp.json()
# Comprobaciones básicas de sanidad
if not data.get("success"):
raise RuntimeError(f"API reportó un fallo: {data}")
# Usa isValid para decidir los siguientes pasos
if data.get("isValid"):
meta = data.get("data", {})
brand = meta.get("card_brand")
type = meta.get("card_type")
level = meta.get("card_level")
issuer = meta.get("issuer_name_bank")
country = meta.get("iso_country_name")
print(f"BIN {BIN} es válido.")
print(f"- Marca: {brand}")
print(f"- Tipo: {type}")
print(f"- Nivel: {level}")
print(f"- Emisor: {issuer}")
print(f"- País: {country}")
else:
print(f"BIN {BIN} no es válido. Mensaje: {data.get('message')}")Ejemplos de respuesta adicionales que puedes probar
Cuando integres, mantén la forma JSON estable en tu analizador. Aquí hay ejemplos completos adicionales utilizando el mismo payload oficial para que puedas verificar el registro, la persistencia y las rutas de prueba de manera consistente:
Ejemplo para tuberías de registro
{
"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
}
}Ejemplo para almacenamiento (por ejemplo, registro en Redis/DB)
{
"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
}
}Ejemplo para servicios de enriquecimiento posteriores
{
"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
}
}Cómo integrar esto en tu flujo de pagos o riesgo
Patrones prácticos que los desarrolladores implementan en producción:
- Asistencia UX del lado del cliente: Tan pronto como un usuario ingrese los primeros 6 dígitos, envía el BIN a tu backend, llama a la API y muestra la marca detectada (por ejemplo, AMERICAN EXPRESS) para reducir errores de entrada. Mantén la clave API del lado del servidor.
- Reglas de enrutamiento: Usa card_type para dirigir transacciones o aplicar umbrales de riesgo. Por ejemplo, maneja CRÉDITO de manera diferente a DÉBITO en la lógica de puntuación posterior.
- Controles de KYC/Fraude: Si isValid es falso, bloquea el intento o requiere verificación adicional antes de continuar.
- Controles del emisor: Si los datos del emisor están disponibles, aplica reglas comerciales por banco o país. Sé defensivo: los campos del emisor pueden estar restringidos o ser nulos.
- Cacheo: Almacena búsquedas recientes de BIN durante horas o días (según tu tolerancia al riesgo) para reducir la latencia y el uso de cuota. Los metadatos de BIN cambian infrecuentemente, pero siempre permite la lógica de actualización.
Validación, seguridad y consideraciones de PCI
Solo envía el BIN (primeros 6 dígitos) a este endpoint. No transmitas ni almacenes el PAN completo en tus registros. Mantén los encabezados de Autorización fuera de los registros también. Construye un pequeño adaptador del lado del servidor que acepte el BIN de tu cliente, llame a esta API y devuelva solo lo que necesitas para renderizar. Si almacenas resultados, almacena solo los metadatos que necesitas y sanitiza valores nulos o de marcador de posición.
Comportamiento alrededor del cual deberías diseñar
- Campos restringidos: Algunos campos del emisor pueden ser “Solo API” o estar enmascarados. No asumas un nombre/website/teléfono del emisor no vacío.
- Manejo de nulos: Los campos de país pueden ser nulos; asegúrate de que tu código tolere eso sin lanzar errores.
- Mensaje y estado: Usa tanto isValid como status para construir mensajes o registros orientados al usuario.
- Reintentos y tiempos de espera: Establece tiempos de espera razonables (por ejemplo, 5–10 segundos) y reintenta solo en tiempos de espera de red, no en resultados de validación 4xx.
- Idempotencia: Las verificaciones de BIN son de solo lectura; puedes reintentar de manera segura fallos de red con retroceso.
Ejemplo de extremo a extremo: patrón de middleware
Aquí hay un flujo pragmático que puedes replicar:
- El frontend envía los primeros 6 dígitos (por ejemplo, 346350) a tu servidor a través de HTTPS.
- Tu servidor llama al endpoint de verificación de BIN con Autorización: Bearer YOUR_API_KEY.
- Si success e isValid son verdaderos, responde al cliente con la marca y tipo para que la UI refleje “AMERICAN EXPRESS · CRÉDITO”.
- Si no es válido, solicita al usuario que verifique la entrada antes de permitir cualquier paso de envío de tarjeta.
- Opcionalmente, almacena en caché por BIN durante un corto TTL para reducir viajes de ida y vuelta en entradas repetidas.
Mapeo campo por campo a la UI típica de pago
- Insignia de marca: Usa data.card_brand (por ejemplo, “AMERICAN EXPRESS”).
- Sugerencia de tipo de tarjeta: Usa data.card_type (por ejemplo, “CRÉDITO”).
- Etiqueta del emisor: Usa data.issuer_name_bank si no es un marcador de posición; de lo contrario, omite.
- Bandera o texto del país: Usa data.iso_country_name cuando esté disponible.
Siempre protege contra marcadores de posición (por ejemplo, “------”) o nulos antes de renderizar.
Lista de verificación de pruebas
- Envía un BIN conocido y afirma que isValid es booleano.
- Asegúrate de que la presencia de data.bin_iin coincida con el BIN consultado.
- Verifica que los campos de marca y tipo sean cadenas y seguros para renderizar.
- Asegúrate de que los valores nulos o de marcador de posición no rompan tu UI o motor de riesgo.
- Confirma que el encabezado de Autorización esté presente en todas las llamadas y nunca se registre.
Trabajando con agentes de IA a través de MCP
Si automatizas flujos de trabajo con herramientas de codificación de IA (por ejemplo, Claude Code, Cursor, Windsurf), puedes llamar a las APIs de Zyla a través del Protocolo de Contexto del Modelo (MCP). Configura tu cliente compatible con MCP para usar el endpoint MCP de Zyla y proporciona tu clave API. Consulta los detalles de integración aquí: MCP. Esto permite que un agente active el mismo flujo de verificación de BIN, mientras que tu servidor aún controla el almacenamiento y registro de claves. Mantén las solicitudes mínimas y valida las salidas antes de actuar en flujos de pago.
Consejos operativos
- Monitoreo: Rastrea el éxito, estado y latencia por solicitud. Alerta sobre picos en fallos.
- Limitación: Implementa limitación de tasa del lado del cliente y retroceso exponencial para ser un buen ciudadano de la API.
- Control de versiones: Las respuestas del proveedor pueden evolucionar; fija tu analizador a campos conocidos e ignora extras inesperados.
- Ciclo de vida de datos: Establece TTL claros en los resultados de BIN almacenados en caché y revalida ante cambios significativos en la lógica de manejo de tarjetas.
Reutilizando la respuesta de muestra en diferentes entornos
Para CI, desarrollo local y staging, utiliza el payload de muestra oficial a continuación como un fixture para que puedas probar tus mapeadores y UI sin filtrar datos reales de tarjetas. Mantén una única fuente de verdad para la forma.
{
"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
}
}Lista de verificación de preparación para producción
- Variables de entorno: Almacena YOUR_API_KEY en un gestor de secretos.
- Políticas de red: Permite HTTPS saliente a zylalabs.com para la URL del endpoint.
- Reintentos limitados en el tiempo: Reintenta solo errores de red; no reintentes fallos de validación.
- Observabilidad: Registra IDs de solicitud y respuestas depuradas (sin secretos) para auditorías.
- Control de acceso: Limita qué servicios pueden llamar al verificador de BIN para reducir el riesgo lateral.
Errores comunes y cómo evitarlos
- Llamadas del lado del cliente con claves expuestas: Siempre usa un proxy a través de tu servidor.
- Asumir que el emisor o país siempre están presentes: Maneja marcadores de posición y nulos con gracia.
- Analizar solo el texto del mensaje: Usa isValid y status para la lógica; el mensaje es para humanos.
- Caché obsoleta: Establece TTL razonables e invalida si detectas metadatos inconsistentes.
¿A dónde ir a continuación?
Navega por otras APIs de Finanzas & Pagos y consolida tus integraciones bajo una cuenta en Zyla API Hub. Mantén tus casos de uso de riesgo, pagos e informes en un solo ecosistema con una única clave API y suscripción.
FAQ
¿La API valida números de tarjeta completos?
No. El endpoint valida un BIN (primeros 6 dígitos) y devuelve metadatos asociados. No envíes PANs completos.
¿Qué autenticación se requiere?
Envía Autorización: Bearer YOUR_API_KEY en el encabezado de cada solicitud.
¿Hay un plan gratuito?
No hay un plan gratuito. Consulta la lista de APIs para el acceso actual. Una prueba de 7 días está típicamente disponible para evaluar el servicio.
¿Con qué frecuencia debo almacenar en caché los resultados de BIN?
Los metadatos de BIN cambian infrecuentemente. Almacena en caché según tu postura de riesgo y horario de actualización. Siempre maneja nulos/marcadores de posición al actualizar.
¿Cómo llamo esto desde un agente de IA?
Usa un cliente compatible con MCP y dirígelo al endpoint MCP de Zyla documentado aquí: MCP. Mantén las claves en un almacén seguro y valida las salidas antes de actuar.
¿Listo para implementar la validación de BIN? Comienza tu evaluación y obtén una clave API en el mercado: Iniciar prueba de 7 días en la API de verificación de BIN del validador de tarjetas de crédito.
