Necesitas validar una tarjeta rápidamente, sin construir tu propia base de datos de BIN o mantener scrapers de proveedores. Al final de esta guía, estarás llamando a un único endpoint para verificar el BIN de una tarjeta y leyendo atributos clave como marca, tipo, nivel, emisor y país, listo para integrarlo en tu proceso de pago, reglas de riesgo o flujos financieros.
Lo que puedes hacer con una simple verificación de BIN
La API de Verificación de Tarjetas devuelve validación y metadatos basados en el BIN (Número de Identificación Bancaria) de una tarjeta. Con una sola solicitud, puedes saber si el BIN es válido y obtener campos como card_brand (por ejemplo, MASTERCARD), card_type (por ejemplo, CRÉDITO), card_level (por ejemplo, ORO), issuer_name_bank y iso_country_code. Los equipos de finanzas y pagos utilizan esto para:
- Pre-validar tarjetas antes de intentar la autorización para reducir llamadas innecesarias a la pasarela.
- Aplicar políticas de enrutamiento o riesgo por marca, tipo, nivel, emisor o país.
- Mejorar los registros de transacciones con detalles del emisor y país para análisis y conciliación.
- Construir herramientas de soporte al cliente que identifiquen atributos de la tarjeta sin almacenar PANs completos.
La API está listada en Zyla API Hub, un mercado de API con más de 10,000 APIs públicas. Obtienes una cuenta, una clave de API y un modelo de suscripción + cuota a través de las APIs que elijas, sin sorpresas de pago por llamada y sin autenticación separada por proveedor.
Cómo comenzar en Zyla API Hub
Abre la página de la API de Verificación de Tarjetas y suscríbete para obtener tu clave. La lista ofrece una prueba de 7 días para que puedas probar en tu entorno primero. Una vez suscrito, tendrás una clave de API que puedes usar en los endpoints de Zyla a través de un encabezado de Autorización.
- Iniciar prueba de 7 días en la API de Verificación de Tarjetas
- Visita la página de inicio del hub para explorar otras APIs de Finanzas y Pagos: zylalabs.com
La autenticación en Zyla es sencilla: añade Authorization: Bearer YOUR_API_KEY a tus solicitudes. La facturación es por suscripción + cuota, no por llamada. Consulta la página de la API para las opciones de acceso y precios actuales.
El endpoint que llamarás
La API de Verificación de Tarjetas expone un único endpoint simple para validar un BIN y devolver metadatos de la tarjeta.
- Método: GET
- URL: https://zylalabs.com/api/2333/card-checker-api/2243/check-card
- Parámetro de consulta requerido: bin (número)
Descripción: ingresa un número de BIN de 6 dígitos en el parámetro bin para validar y recuperar detalles de la tarjeta.
Ejemplo de cURL (listo para copiar y pegar)
curl -s -X GET "https://zylalabs.com/api/2333/card-checker-api/2243/check-card?bin=444444" \
-H "Authorization: Bearer YOUR_API_KEY"
Respuesta de muestra oficial
{
"status": 200,
"success": true,
"isValid": true,
"message": "El número BIN es 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": "TURQUÍA",
"iso_country_code": "TR"
}
}
Lo que debes leer de esta carga útil:
- isValid: booleano que indica si el BIN proporcionado es reconocido como válido.
- message: estado de validación legible por humanos.
- data.bin_iin: el BIN/IIN asociado con el resultado.
- data.card_brand, data.card_type, data.card_level: identificadores útiles para el enrutamiento y etiquetas de UI.
- data.issuer_name_bank, issuer_bank_phone, issuer_bank_website: detalles del emisor que puedes almacenar para referencia.
- data.iso_country_name, data.iso_country_code: información del país para verificaciones de cumplimiento y reglas de fraude.
Ejemplo en Python: verificar un BIN y ramificar según la validación
El fragmento a continuación demuestra una simple llamada GET, analiza la respuesta y muestra dónde integrar tu lógica de políticas (por ejemplo, rechazar tarjetas de crédito prepagadas, permitir solo ciertos países o solicitar verificación adicional).
import os
import requests
API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
BASE_URL = "https://zylalabs.com/api/2333/card-checker-api/2243/check-card"
def check_bin(bin_number: str) -> dict:
url = f"{BASE_URL}?bin={bin_number}"
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(url, headers=headers, timeout=10)
resp.raise_for_status()
return resp.json()
if __name__ == "__main__":
result = check_bin("444444")
# Campos principales que usarás comúnmente
is_valid = result.get("isValid")
message = result.get("message")
data = result.get("data", {}) or {}
print("BIN válido:", is_valid)
print("Mensaje:", message)
if is_valid:
brand = data.get("card_brand")
card_type = data.get("card_type")
level = data.get("card_level")
issuer = data.get("issuer_name_bank")
country_code = data.get("iso_country_code")
print("Marca:", brand)
print("Tipo:", card_type)
print("Nivel:", level)
print("Emisor:", issuer)
print("País:", country_code)
# Ejemplos de ganchos de políticas:
# - Si necesitas restringir por país:
# if country_code not in {"US", "CA", "GB"}:
# print("Ruta a revisión manual")
# - Si solo aceptas ciertas marcas/tipos:
# if brand != "MASTERCARD" or card_type != "CREDIT":
# print("Mostrar método de pago alternativo")
else:
# Fallback cuando el BIN no es válido (por ejemplo, pedir al usuario que vuelva a ingresar)
print("BIN no válido; solicitar corrección.")
Notas de implementación que ahorran tiempo
- Solo se requiere el parámetro de consulta bin. Usa los primeros 6 dígitos del número de tarjeta; no transmitas PANs completos para reducir la exposición PCI en tus sistemas.
- Rendimiento: las búsquedas de BIN son ligeras, ideales para activar en eventos de desenfoque en tu formulario de pago o del lado del servidor antes de la autorización. Considera un corto almacenamiento en caché del cliente o del borde, clave por BIN, para reducir solicitudes repetidas durante una sesión.
- UX de respaldo: si isValid es falso, vuelve a solicitar al usuario los primeros 6 dígitos. Mantén el texto de error neutral: “Por favor, verifica los primeros 6 dígitos de tu tarjeta.”
- Normalización: almacena los valores de marca/tipo/nivel tal como los proporciona la API (por ejemplo, MASTERCARD, CRÉDITO) y mapea a cualquier enumeración interna en tu capa de frontera.
- Auditoría: registra la bandera isValid, bin_iin, marca, tipo, nivel, emisor y iso_country_code en tus registros de auditoría de pagos. Evita almacenar el número completo de la tarjeta.
Casos de uso en finanzas y pagos en el mundo real
- Optimización del formulario de pago: después de que un usuario ingrese los primeros 6 dígitos, detecta card_brand y muestra el ícono de marca apropiado. Si la marca o tipo no es compatible, solicita otra tarjeta antes del evento de envío.
- Reglas de enrutamiento: envía tarjetas MASTERCARD CRÉDITO ORO a una pasarela con la mejor tasa de intercambio o perfil de aceptación para esa marca/tipo.
- Filtros de cumplimiento: desautoriza o marca BINs de países embargados o no soportados verificando iso_country_code.
- Heurísticas de fraude: combina issuer_name_bank y iso_country_code con geolocalización IP, país de facturación y señales de dispositivo. Las discrepancias pueden aumentar los puntajes de riesgo.
- Soporte al cliente: cuando un pago falla, los agentes de soporte pueden identificar rápidamente el emisor y la marca desde el BIN para guiar a los usuarios a llamar a su banco si es necesario.
Llama a la misma API desde agentes de IA a través de MCP
Si automatizas tareas utilizando clientes compatibles con MCP (por ejemplo, asistentes de código que pueden llamar herramientas), puedes invocar las APIs de Zyla a través del endpoint MCP. Dirige tu cliente a:
https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
Desde allí, instruye al agente para que llame al endpoint de la API de Verificación de Tarjetas utilizando el método GET y el parámetro de consulta bin. Pasará automáticamente tu encabezado de Autorización si tu cliente MCP está configurado con la clave de API. Para información general sobre el uso de MCP, consulta la página MCP.
Cómo integrar en tu flujo de pagos
1) Pre-verificación del lado del cliente (opcional)
Cuando el usuario ingresa los primeros 6 dígitos, llama a tu backend solo con el BIN. Tu backend luego llama a la API de Verificación de Tarjetas y devuelve una carga útil mínima (marca, tipo, nivel, país). Esto evita exponer tu clave de API de Zyla al navegador.
2) Validación del lado del servidor antes de la autorización
Justo antes de crear una intención de pago o autorización, llama a la API con el mismo BIN para confirmar que es válido y capturar el emisor y el país para tus registros y reglas. Si isValid es falso, interrumpe el intento y solicita una tarjeta diferente.
3) Registro y análisis
Almacena campos clave junto a tu intento de transacción para que puedas segmentar rechazos, aceptaciones y contracargos por marca/tipo/emisor/país. Esto ayuda a ajustar el enrutamiento y los modelos de fraude con el tiempo.
Patrones de manejo de errores
- Capa HTTP: trata los códigos no 2xx como transitorios o terminales según tu política de reintentos. Los tiempos de espera de red pueden reintentarse rápidamente; los 4xx/5xx persistentes deben registrarse con IDs de correlación.
- Semántica de respuesta: usa el booleano isValid y el mensaje para flujos amigables para el usuario. Evita analizar issuer_bank_website para el enrutamiento a menos que tengas una razón específica; issuer_name_bank y país son impulsores más estables.
- Resiliencia: implementa un retroceso exponencial corto con jitter en errores transitorios. Almacena en caché búsquedas de BIN positivas brevemente para evitar que picos repentinos impacten el proceso de pago.
Notas de seguridad y privacidad
- Nunca envíes números de tarjeta completos a tu endpoint de verificación de BIN. Extrae los primeros 6 dígitos y descarta el resto para esta verificación.
- Mantén tu clave de API de Zyla del lado del servidor; no la incrustes en clientes web o móviles. Usa tu backend como un proxy delgado si deseas una experiencia instantánea para el cliente.
- Registra solo lo que necesitas. BIN, marca, tipo, nivel, emisor y país son típicamente suficientes para análisis y reglas.
Trabajando dentro de las limitaciones de ingeniería
- Presupuesto de latencia: la verificación de BIN es rápida y puede realizarse durante la entrada del formulario o justo antes de la autorización. Si eres extremadamente sensible a la latencia, añade un caché del cliente o del borde claveado por BIN para un TTL corto.
- Idempotencia: la solicitud es una lectura; considérela idempotente. Puedes reintentar de manera segura en fallos transitorios.
- Internacionalización: iso_country_code es ISO alpha-2 (por ejemplo, TR). Mapea a tu capa de localización para nombres de visualización o reglas comerciales específicas de país.
Referencia: Resumen del endpoint
- GET https://zylalabs.com/api/2333/card-checker-api/2243/check-card
- Parámetro de consulta: bin (número, requerido). Ejemplo: 444444
- Encabezado de autenticación: Authorization: Bearer YOUR_API_KEY
- Campos de respuesta que típicamente usarás: isValid, message, data.bin_iin, data.card_brand, data.card_type, data.card_level, data.issuer_name_bank, data.iso_country_code
Consejos de calidad de vida para producción
- Activa la integración con un flag de función para que puedas implementarla por mercado o segmento.
- Agrega observabilidad: rastrea el conteo de solicitudes, tasas 2xx/4xx/5xx y latencia p95 para la verificación de BIN.
- Crea invariantes en las pruebas: simula el JSON anterior para verificar tu lógica de enrutamiento para MASTERCARD CRÉDITO ORO en TR.
- Documenta tu mapeo interno de cadenas proporcionadas por la API (por ejemplo, “MASTERCARD”) a tus enumeraciones para prevenir desajustes silenciosos.
FAQ
¿Cuál es el mínimo que necesito para llamar a la API?
Una clave de API de Zyla válida y los primeros 6 dígitos de la tarjeta (parámetro bin). Añade el encabezado Authorization: Bearer YOUR_API_KEY.
¿Puedo usar esto en el proceso de pago sin almacenar números de tarjeta completos?
Sí. Envía solo los primeros 6 dígitos (BIN). No envíes ni almacenes el PAN completo para este paso de validación.
¿Qué campos debo persistir?
Típicamente: isValid, bin_iin, card_brand, card_type, card_level, issuer_name_bank y iso_country_code. Estos son los más útiles para enrutamiento, fraude e informes.
¿Hay un plan gratuito?
No hay plan gratuito. La lista ofrece una prueba de 7 días para que puedas evaluar antes de comprometerte. Consulta la página de la API para las opciones de acceso y precios actuales.
¿Puedo llamarlo desde un agente de codificación de IA?
Sí. Configura tu cliente compatible con MCP para usar el endpoint MCP de Zyla, luego haz que emita una llamada GET a la API de Verificación de Tarjetas con el parámetro bin. Consulta la página de MCP vinculada arriba para más detalles.
¿Listo para implementar verificaciones de tarjetas en minutos? Abre la lista y comienza tu prueba: Iniciar prueba de 7 días en la API de Verificación de Tarjetas. Explora más integraciones financieras en zylalabs.com y lanza tu flujo de validación esta semana.