Necesitas validar una tarjeta de pago rápidamente, idealmente antes de cobrarla o enrutar la transacción. Al final de esta guía, tendrás una llamada funcional que verifica el BIN de una tarjeta (primeros 6 dígitos) y devuelve la marca, tipo, nivel, emisor y país utilizando una única API de Finanzas en Zyla API Hub—lista para pegar en tu integración hoy.
Qué hace esta API y cuándo usarla
La API de Verificación de Tarjetas verifica un BIN de 6 dígitos y devuelve metadatos de la tarjeta como marca (por ejemplo, MASTERCARD), tipo (CREDITO/DEBITO), nivel (por ejemplo, ORO), nombre del emisor y país del emisor. Las aplicaciones utilizan esto para:
- Rechazar marcas o tipos de tarjetas no soportados antes de la autorización.
- Enrutar transacciones al procesador correcto según el país del emisor.
- Pre-completar información del emisor para soporte al cliente o verificaciones de cumplimiento.
- Mejorar las verificaciones de fraude validando que el BIN sea legítimo.
Zyla API Hub centraliza miles de APIs de Finanzas y Pagos bajo una sola cuenta, una clave API y un modelo de suscripción. Puedes gestionar tu acceso y uso a través de los servicios desde tu panel de desarrollador en zylalabs.com.
Comenzando en Zyla API Hub
Para integrar rápidamente:
- Abre la página de la API de Verificación de Tarjetas en Zyla: Iniciar prueba de 7 días en la API de Verificación de Tarjetas.
- Haz clic en Suscribirse (o Iniciar Prueba Gratuita cuando esté disponible). Para esta API, la primera API ofrece una prueba de 7 días o 50 solicitudes.
- Copia tu clave API desde tu panel. La autenticación es a través del encabezado HTTP: Authorization: Bearer YOUR_API_KEY.
La facturación es por suscripción + cuota (no por llamada). No hay Plan Gratuito. Para opciones de acceso y precios actuales, consulta la página de la API en Zyla.
Endpoint que llamarás
La API de Verificación de Tarjetas proporciona un único endpoint simple que valida un BIN y devuelve detalles de la tarjeta. Todas las solicitudes son GET y se autentican con tu token de portador.
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
Qué hace: Valida el BIN proporcionado y devuelve una carga útil JSON que contiene el estado de validación y metadatos de la tarjeta (marca, tipo, nivel, emisor y país).
cURL que puedes pegar y ejecutar
Reemplaza YOUR_API_KEY con la clave de tu panel de Zyla y ejecuta esto en tu terminal:
curl -s -X GET "https://zylalabs.com/api/2333/card-checker-api/2243/check-card?bin=444444"
-H "Authorization: Bearer YOUR_API_KEY"Ejemplo de respuesta oficial
{
"status": 200,
"success": true,
"isValid": true,
"message": "El número BIN es válido.",
"data": {
"bin_iin": "557829",
"card_brand": "MASTERCARD",
"card_type": "CREDITO",
"card_level": "ORO",
"issuer_name_bank": "AKBANK T.A.S.",
"issuer_bank_website": "------",
"issuer_bank_phone": "4442525",
"iso_country_name": "TURQUÍA",
"iso_country_code": "TR"
}
}Campos que típicamente usarás:
- status: código de estado similar a HTTP devuelto en la carga útil (200 indica éxito).
- success: indicador booleano de éxito para la operación de la API.
- isValid: si el BIN es reconocido como válido.
- message: un resultado de validación legible por humanos.
- data.bin_iin: BIN/IIN normalizado devuelto por la API.
- data.card_brand: red de tarjetas (por ejemplo, MASTERCARD, VISA, etc.).
- data.card_type: CREDITO/DEBITO (útil para enrutar o cálculos de tarifas).
- data.card_level: por ejemplo, ORO, PLATINO (a veces utilizado para lógica de beneficios).
- data.issuer_name_bank: nombre del banco emisor.
- data.issuer_bank_phone: teléfono del emisor (para flujos de soporte).
- data.iso_country_name / data.iso_country_code: país del emisor (por ejemplo, TR para Turquía).
Ejemplo en Python: validar un BIN y lógica de ramificación
Este ejemplo llama al mismo endpoint y utiliza los campos de respuesta para permitir solo tarjetas de crédito MASTERCARD emitidas en un país específico. Ajusta la lógica a tus necesidades.
import os
import requests
API_KEY = os.getenv("ZYLA_API_KEY", "YOUR_API_KEY")
BIN = "444444" # primeros 6 dígitos de la tarjeta
url = "https://zylalabs.com/api/2333/card-checker-api/2243/check-card"
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()
if not data.get("success"):
raise RuntimeError(f"La verificación de la tarjeta falló: {data}")
if not data.get("isValid"):
print("El BIN no es válido. Bloquear o retroceder.")
else:
meta = data.get("data", {})
brand = meta.get("card_brand")
ctype = meta.get("card_type")
country = meta.get("iso_country_code")
issuer = meta.get("issuer_name_bank")
print(f"BIN válido. Marca={brand}, Tipo={ctype}, Emisor={issuer}, País={country}")
# Política de ejemplo: aceptar solo tarjetas de crédito Mastercard de TR
if brand == "MASTERCARD" and ctype == "CREDITO" and country == "TR":
print("Proceder con el flujo de autorización.")
else:
print("Enrutar de manera diferente o rechazar según las reglas comerciales.")Notas de integración práctica que ahorran tiempo
- Longitud del BIN: Solo se requieren los primeros 6 dígitos (el endpoint espera un número de 6 dígitos).
- Cuándo llamar: Ejecuta la verificación tan pronto como puedas después de recopilar los dígitos de la tarjeta, antes de enviar una autorización a tu PSP.
- Cacheo: Las asignaciones de BIN a metadatos cambian con poca frecuencia. Almacena en caché las respuestas exitosas (por ejemplo, de 24 horas a 7 días) para reducir la latencia y el uso de cuota, y invalida por BIN.
- Privacidad: Nunca envías PANs completos a esta API—solo el BIN. Esto reduce el alcance para el manejo de datos sensibles en tu servicio.
- Timeouts y reintentos: Usa un tiempo de espera de cliente razonable (por ejemplo, 5–10s). Para problemas de red transitorios, un solo reintento con jitter suele ser suficiente antes de retroceder a un flujo predeterminado.
- Cuotas: Esta API funciona con un modelo de suscripción + cuota (no por llamada). Monitorea tu uso en tu panel de Zyla y agrupa o almacena en caché para mantenerte dentro de los límites del plan.
- Manejo de fallos: Si el éxito es falso o la solicitud falla, decide si permitir una autorización de mejor esfuerzo o requerir una red/tipo soportado. Registra la carga útil para auditoría.
- Auditoría: Persiste el BIN y los campos de datos de respuesta en los que confías (marca, tipo, emisor, país) junto con tu registro de intento de pago para trazabilidad.
Ejemplo de flujo de extremo a extremo
- El cliente ingresa el número de tarjeta en tu formulario de pago.
- Tu frontend extrae los primeros seis dígitos (BIN) y los envía a tu backend a través de TLS.
- Tu backend llama a la API de Verificación de Tarjetas con ese BIN.
- Si isValid es verdadero, utiliza card_brand, card_type y iso_country_code para elegir una ruta de procesador o hacer cumplir la política (por ejemplo, solo se permite CREDITO).
- Almacena en caché el resultado del BIN. Continúa con la autorización o flujos de 3DS según corresponda.
Casos de uso que puedes implementar esta semana
- Control de aceptación de tarjetas: Bloquear marcas o tipos no soportados temprano para reducir rechazos en la pasarela más adelante.
- Enrutamiento basado en geolocalización: Enviar transacciones a un procesador optimizado para el país del emisor utilizando iso_country_code.
- Cálculo de tarifas: Diferenciar tarifas según card_type o card_level (por ejemplo, ORO/PLATINO) en tu lógica de precios.
- Herramientas de soporte: Mostrar issuer_name_bank y teléfono a los agentes para acelerar las escalaciones.
- Reglas de riesgo: Combinar la validez del BIN con verificaciones de dispositivo, IP y velocidad para aumentar o disminuir la fricción.
Trabajando con el endpoint MCP de Zyla desde agentes de IA
Si utilizas entornos de codificación o agentes de IA (por ejemplo, Claude Code, Cursor, Windsurf), puedes llamar a las APIs de Zyla a través del puente MCP. Configura tu cliente para conectarse al endpoint MCP de Zyla y proporciona tu clave API. Aprende más aquí: MCP. Desde allí, el agente puede invocar el mismo endpoint de Verificar tarjeta con el parámetro bin y tu token de portador bajo el capó.
Esto te permite prototipar solicitudes como “Valida el BIN 444444 y dime el país del emisor” y conectar el resultado directamente en tu generación de código o manuales de ejecución—sin salir de tu IDE.
Lista de verificación de pruebas
- Camino feliz: Un BIN válido conocido devuelve success=true e isValid=true con campos de datos completos.
- Entrada inválida: Entrada no numérica o de longitud incorrecta es rechazada o devuelve isValid=false (manejar de manera adecuada en tu UI).
- Ramificación de políticas: Confirma que tus reglas de marca/tipo/país se reflejan correctamente en los resultados de aceptación y enrutamiento.
- Cacheo: Verifica que las verificaciones repetidas para el mismo BIN accedan a la caché y reduzcan las llamadas salientes.
- Observabilidad: Registra el estado, isValid y campos de datos clave; añade métricas para la tasa de aciertos de caché y errores de API.
Referencia: Resumen del endpoint
- Verificar tarjeta (GET): https://zylalabs.com/api/2333/card-checker-api/2243/check-card
- Parámetro requerido: bin (número)
- Autenticación: Authorization: Bearer YOUR_API_KEY
- Devuelve: status, success, isValid, message y data con metadatos de BIN/IIN (marca, tipo, nivel, emisor, país)
Por qué Zyla API Hub para integraciones de Finanzas
Con más de 10,000 APIs públicas accesibles bajo una sola cuenta y una clave, Zyla reduce la sobrecarga para equipos que implementan múltiples integraciones. Puedes suscribirte a la API de Verificación de Tarjetas y combinarla con otras herramientas de Finanzas y Pagos a medida que tu stack evoluciona, todo desde tu panel de Zyla en zylalabs.com.
FAQ
¿Puedo validar un PAN completo o solo el BIN?
Este endpoint valida solo un BIN de 6 dígitos. No envíes PANs completos. Usa tu pasarela de pago para validación y autorización a nivel de PAN.
¿Qué encabezado uso para la autenticación?
Envía Authorization: Bearer YOUR_API_KEY con cada solicitud.
¿Qué sucede si el BIN no es válido?
La respuesta indicará isValid como falso (y el éxito aún puede ser verdadero si la llamada se ejecutó). Usa esa señal para ajustar tu flujo, por ejemplo, bloquear la tarjeta o solicitar un método de pago alternativo.
¿Cuántas solicitudes puedo hacer?
Zyla utiliza suscripción + cuota (no por llamada). Para la primera API, hay una prueba de 7 días o 50 solicitudes. Consulta la página de la API para límites y precios actuales.
¿Puedo llamar a esta API desde un agente de IA?
Sí. Conecta tu agente al endpoint MCP de Zyla y autentica con tu clave API. El agente puede invocar el endpoint de Verificar tarjeta con el parámetro bin.
Implementa tu integración
Valida BINs, enruta transacciones de manera inteligente y reduce rechazos prevenibles con una sola llamada. Comienza aquí y obtén tu clave: Iniciar prueba de 7 días en la API de Verificación de Tarjetas. Una vez suscrito, utiliza el endpoint GET anterior con tu token de portador y envía tu flujo de Finanzas esta semana.
