Trabajando con la API de Verificación de Tarjetas

Necesitas validar y enriquecer los BIN de tarjetas esta semana para poder marcar pagos riesgosos, enrutar transacciones correctamente o completar datos del emisor en tu pila financiera. Al final de esta guía, realizarás solicitudes autenticadas a la API de Verificación de Tarjetas en Zyla API Hub, interpretarás la respuesta de manera confiable y la integrarás en un flujo de trabajo de pago o riesgo en producción.

Qué hace la API de Verificación de Tarjetas

La API de Verificación de Tarjetas verifica el BIN (Número de Identificación Bancaria, los primeros 6 dígitos de un número de tarjeta) y devuelve detalles del emisor y de la red. Con una sola llamada GET, sabrás si el BIN es válido y recuperarás campos estructurados que incluyen la marca de la tarjeta, tipo, nivel, nombre del emisor, teléfono del emisor e información del país ISO. Los equipos utilizan esto para:

• Validar los BIN en el proceso de pago antes de intentar la autorización.
• Identificar marcas de tarjetas (por ejemplo, MASTERCARD) y tipos (por ejemplo, CRÉDITO) para la lógica de enrutamiento y cumplimiento.
• Impulsar la puntuación de riesgo con señales del país del emisor (por ejemplo, hacer coincidir con el país de facturación).
• Potenciar herramientas de soporte que muestran rápidamente qué banco emitió una tarjeta.

Comenzando en Zyla API Hub

La API de Verificación de Tarjetas está disponible en Zyla API Hub, que alberga más de 10,000 APIs públicas en finanzas y categorías relacionadas. Te suscribes una vez, recibes una única clave API y llamas al endpoint listo para usar de inmediato. La primera API que pruebas incluye una prueba de 7 días o 50 solicitudes, con suscripción + cuota (no es pago por llamada). Consulta la página de la API para conocer las opciones de acceso y precios actuales.

1. Abre la lista de APIs y suscríbete: Inicia prueba de 7 días en la API de Verificación de Tarjetas.
2. Copia tu clave API.
3. Usa Authorization: Bearer YOUR_API_KEY en cada solicitud al endpoint documentado a continuación.

Referencia de endpoint

Verificar tarjeta

Método: GET

URL: https://zylalabs.com/api/2333/card-checker-api/2243/check-card

Descripción: Valida un BIN de 6 dígitos y devuelve metadatos del emisor y de la red.

Parámetro de consulta requerido:

• bin (número): El BIN de 6 dígitos. Ejemplo: 444444

Ejemplo de cURL (copiar/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 ejemplo 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 típicamente usarás de esta carga útil:

• isValid: Indicador booleano que indica que el BIN es reconocido y válido.
• data.bin_iin: El BIN/IIN devuelto para la búsqueda (cadena).
• data.card_brand: Red/marca (por ejemplo, MASTERCARD).
• data.card_type: Categoría del producto de la tarjeta (por ejemplo, CRÉDITO).
• data.card_level: Nivel/tier (por ejemplo, GOLD) si está disponible.
• data.issuer_name_bank: Nombre del banco emisor.
• data.issuer_bank_phone: Teléfono de contacto del emisor.
• data.iso_country_name / iso_country_code: País del emisor (nombre y código alfa-2 ISO).

Ejemplo en Python

Este ejemplo llama al endpoint, verifica la validez e imprime los campos que puedes usar para reglas de pago o puntuación de riesgo. Reemplaza YOUR_API_KEY con tu clave.

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://zylalabs.com/api/2333/card-checker-api/2243/check-card"

def fetch_bin_info(bin_number: str) -> dict:
headers = {
"Authorization": f"Bearer {API_KEY}"
}
params = {
"bin": bin_number
}
resp = requests.get(BASE_URL, headers=headers, params=params, timeout=10)
# Si el Hub devuelve un HTTP no 200, lanza para visibilidad en registros/alertas.
resp.raise_for_status()
return resp.json()

def main():
# BIN de ejemplo
bin_number = "444444"
data = fetch_bin_info(bin_number)

# Comprobaciones mínimas que debes realizar antes de usar los campos
if not data.get("success"):
print("Búsqueda no exitosa:", data)
return

print("BIN válido:", data.get("isValid"))
info = data.get("data", {}) or {}

print("BIN/IIN resuelto:", info.get("bin_iin"))
print("Marca:", info.get("card_brand"))
print("Tipo:", info.get("card_type"))
print("Nivel:", info.get("card_level"))
print("Emisor:", info.get("issuer_name_bank"))
print("Teléfono del emisor:", info.get("issuer_bank_phone"))
print("País del emisor:", info.get("iso_country_name"), "(", info.get("iso_country_code"), ")")

# Ejemplo: regla de riesgo ligera
# if info.get("iso_country_code") not in {"US", "CA", "GB"}:
# flag_reason = "issuer_country_out_of_region"

if __name__ == "__main__":
main()

Notas de implementación que ahorran tiempo

• Autorización: Siempre envía Authorization: Bearer YOUR_API_KEY exactamente como se muestra. No coloques la clave en los parámetros de consulta.
• Formato de BIN: El endpoint espera un BIN de 6 dígitos en el parámetro de consulta bin. Elimina espacios, no dígitos y evita enviar PANs completos; solo se requiere el BIN.
• Cacheo: Los mapeos de BIN a emisor son relativamente estables. Almacena en caché los resultados indexados por BIN en tu sistema para reducir llamadas repetidas y latencia. Invalida cuando observes cambios de emisor en tus registros.
• Fallbacks elegantes: Si success es falso o isValid es falso, mantén tu proceso de pago receptivo. Por ejemplo, puedes predeterminar el manejo genérico de tarjetas y proceder a la autorización mientras aumentas la supervisión.
• Registro: Registra data.bin_iin y campos del emisor para observabilidad. Evita registrar números de tarjeta completos; solo debes manejar el BIN para esta búsqueda.
• Pruebas: Usa una mezcla de BINs comunes a través de marcas y regiones para verificar que tu lógica de enrutamiento o riesgo maneje diferentes combinaciones de marca/tipo/nivel/país.

Flujos de trabajo financieros comunes que puedes implementar con esta API

• Pre-validación de pago: Llama a la API después de formatear la entrada de la tarjeta y antes de crear una intención de pago. Rechaza BINs evidentemente inválidos temprano o requiere verificación adicional para emisores específicos.
• Coincidencia de país del emisor: Compara iso_country_code con el país de facturación o IP para activar autenticación adicional cuando no coincidan.
• Sugerencias de enrutamiento de red: Dirige MASTERCARD frente a otras marcas a diferentes adquirentes o aplica políticas 3DS personalizadas por card_type.
• Enriquecimiento de soporte al cliente: Cuando un cargo falla con un rechazo genérico, muestra issuer_name_bank y issuer_bank_phone en la consola del agente para acelerar la resolución.
• Analítica y monitoreo: Agrega transacciones por issuer_name_bank o iso_country_code para rastrear rendimiento y patrones de contracargos.

Manejo de errores y resiliencia

La respuesta de ejemplo demuestra una búsqueda exitosa con status: 200 y success: true. En tu integración:

• Verifica los códigos de estado HTTP y maneja las respuestas no 2xx de manera apropiada (reintenta con retroceso si es necesario, dependiendo de tu cola de trabajos o estrategia de pago).
• Inspecciona success e isValid antes de usar los campos de datos. Si alguna de las verificaciones falla, continúa con valores predeterminados conservadores.
• Valida que los datos existan antes de leer campos anidados para evitar problemas de None/KeyError.

Puntos de seguridad y cumplimiento

• Solo envía el BIN (6 dígitos). No transmitas PANs completos a este servicio.
• Almacena tu clave API en secretos del lado del servidor (por ejemplo, variables de entorno o un administrador de secretos). No la expongas en el código del lado del cliente.
• Registra los detalles mínimos necesarios y evita PII en los registros. El BIN en sí no es suficiente para identificar a un titular de tarjeta, pero combínalo con precaución con otros atributos en tu sistema.

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

Puedes invocar APIs en Zyla a través de un cliente compatible con MCP utilizando el endpoint MCP. Apunta tu cliente MCP a la siguiente URL e incluye tu clave API de Zyla:

MCP

Desde allí, tu agente de IA puede llamar al mismo endpoint de la API de Verificación de Tarjetas como se muestra arriba utilizando el encabezado de Autorización. Usa el agente para automatizar el enriquecimiento de datos (por ejemplo, validación de BIN durante la triage de pedidos sospechosos) mientras mantienes el mismo método HTTP, URL y parámetros documentados en esta publicación.

Uniendo todo

En un flujo típico de backend:

1. El cliente recopila la entrada de la tarjeta y envía solo el BIN (primeros 6 dígitos) a tu servidor.
2. Tu servidor solicita GET /check-card con bin=XXXXXX y Authorization: Bearer YOUR_API_KEY.
3. Si success e isValid son verdaderos, usa data.card_brand, data.card_type y el país del emisor para aplicar reglas de enrutamiento o riesgo.
4. Almacena en caché la respuesta por BIN para evitar búsquedas repetidas.
5. Procede con tu intento de pago o escala a 3DS/desafío según las reglas que definiste.

Lista de verificación de solución de problemas

• 401 o problema de autenticación similar: Confirma que tu encabezado de Autorización sea exactamente Authorization: Bearer YOUR_API_KEY y que la clave esté activa.
• No hay campos en data: Asegúrate de que el parámetro bin esté presente y tenga exactamente 6 dígitos.
• Errores inesperados: Registra el cuerpo JSON completo y los encabezados relevantes (excluyendo secretos) para diagnóstico; reintenta de manera responsable desde una cola para evitar bloquear el pago.
• Emisor diferente al esperado: Las bases de datos de emisores evolucionan; actualiza tu caché y vuelve a verificar la última respuesta para el BIN.

FAQ

¿Cómo se ve un BIN válido?
Un BIN válido tiene exactamente 6 dígitos. Elimina cualquier espacio o separador de la entrada del usuario antes de enviar el bin.

¿Necesito enviar un número de tarjeta completo?
No. Envía solo el BIN de 6 dígitos en el parámetro de consulta bin.

¿Cómo me autentico?
Incluye un encabezado de Autorización con el valor Bearer YOUR_API_KEY en cada solicitud.

¿Cómo se maneja la facturación?
Las APIs en Zyla utilizan un modelo de suscripción + cuota (no pago por llamada). La primera API que pruebas incluye una prueba de 7 días o 50 solicitudes. Consulta la página de la API para conocer las opciones de acceso y precios actuales.

¿Puedo llamar a esto desde un agente de IA?
Sí. Usa un cliente compatible con MCP apuntando al endpoint MCP y asegúrate de que el encabezado de Autorización esté configurado cuando tu agente realice la llamada GET.

¿Listo para validar y enriquecer los BIN de tarjetas en tu pila financiera? Suscríbete y obtén tu clave en la lista de la API de Verificación de Tarjetas: Inicia prueba de 7 días en la API de Verificación de Tarjetas. Pega el cURL anterior en tu terminal, confirma isValid y envía tu integración.