Changelog

Historial de cambios de la API de Zelta Pay. Cada versión incluye las nuevas funcionalidades, cambios y correcciones realizadas.

v1.2.0 (Actual)

Publicada en 2026.

API de Integración (proyectos)

Nueva familia de endpoints con alcance de proyecto (cada proyecto tiene una API key y un webhook) que permite usar Zelta Pay como motor de pagos de tu software: guarda la tarjeta del cliente una vez y luego mueve el dinero por API.

• — modelo de proyectos, tipos de producto y flujo de captura → cargo/suscripción
• — GET /v1/products y GET /v1/products/{productCode} (catálogo de solo lectura; se gestiona desde el dashboard)
• — GET/POST /v1/customers, GET /v1/customers/{id} y POST /v1/customers/{id}/vault
• — POST /v1/collections/links (captura de tarjeta) y POST /v1/collections/payment-links (cobra y captura)
• — crear, listar, actualizar items, cambiar de cliente, cancelar, reactivar y listar facturas
• — POST /v1/charges (cobro único a un cliente vaulteado, con proración e idempotencia), GET /v1/charges y GET /v1/charges/{id}

Nuevos tipos de link de pago

• customer_collection — captura y vaultea la tarjeta sin cobrar
• customer_payment — cobra y vaultea en el mismo checkout (requiere productCode)
• Nuevos filtros linkType y search en

Monto máximo aumentado

• El monto máximo de un link o pago sube de $2,000.00 a $10,000.00 (1000000 centavos)

Nuevos estados

• Nuevo estado processing en los links de pago
• Estados de transacción: pending, processing, paid, failed, unknown, deferred

Nuevos eventos de webhook

La documenta ahora los 19 tipos de evento. Se agregan, entre otros: payment.failed, payment_link.rejected, charge.succeeded, charge.failed, charge.deferred, charge.unknown, la familia subscription.*, invoice.paid, invoice.payment_failed, customer.created y receipt.created.

Idempotencia en la API

• Nuevo campo idempotencyKey en POST /v1/charges: los reintentos con la misma clave nunca cobran dos veces

v1.1.0

Publicada en 2026.

Selección de métodos de pago

Nuevo campo paymentMethods para controlar qué métodos de pago están disponibles en cada link.

• Nuevo campo paymentMethods en
• Valores permitidos: "yappy" y "card"
• Sin duplicados, al menos 1 elemento cuando se especifica
• Si no se incluye, se habilitan todos los métodos activos de la cuenta
• Nuevo código de error ERR_INACTIVE_PAYMENT_METHOD cuando se solicita un método de pago que no está activo en la cuenta

Solicitud de email al cliente

Nuevo campo requestCustomerEmail para controlar si se solicita el email al cliente en la página de pago.

• Nuevo campo requestCustomerEmail en
• Default: true (se solicita email al cliente)
• No puede ser true cuando se proporciona customerEmail
• Si se envía customerEmail, requestCustomerEmail se establece automáticamente en false

Filtro por proveedor de pago

Nuevo parámetro de consulta paymentProvider para filtrar links al listarlos.

• Nuevo parámetro paymentProvider en
• Valores permitidos: yappy, card

Campos actualizados en las respuestas

Los siguientes campos se incluyen ahora en las respuestas de los endpoints de links de pago:

• paymentMethods — Array de métodos de pago habilitados
• requestCustomerEmail — Si se solicita email al cliente en la página de pago

La respuesta de ahora devuelve un formato compacto con los campos esenciales: hashUrl, customerName, concept, amount, status, createdAt y cancelledAt.

Actualizaciones del payload de webhooks

• Nuevo campo transaction.isTest en el payload de , indicando si la transacción es de prueba

v1.0.0

Publicada en 2025.

Lanzamiento inicial

Primera versión de la API de Zelta Pay con todas las funcionalidades base.

Endpoints

• — Listar links de pago con paginación y filtros
• — Crear un link de pago
• — Obtener un link de pago específico
• — Cancelar un link de pago

Autenticación

• Autenticación mediante header X-API-Key
• Gestión de API keys desde el

Paginación

• Parámetros lim y off para paginación
• Campo total en las respuestas de listas

Validación

• Montos en centavos: rango de 100 a 200000 ($1.00 a $2,000.00)
• Campos requeridos: concept, amount, customerName, isTest
• Metadata: máximo 20 llaves, máximo 8192 bytes
• URL de redirección: máximo 2048 caracteres

Rate Limiting

• 60 solicitudes por minuto por API key
• Ventana deslizante de 1 minuto
• Headers de respuesta: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset

Webhooks

• Notificaciones en tiempo real de eventos de pago
• Verificación de firmas con zeltapay-signature y zeltapay-timestamp
• Soporte para

Formato de respuesta

• Respuestas JSON con campo success (boolean)
• Timestamps en formato ISO 8601
• Códigos de error descriptivos con prefijo ERR_

Códigos de estado HTTP

• 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 429 Too Many Requests

Problemas conocidos

Ninguno.

Versiones futuras

Estamos trabajando en nuevas funcionalidades para la API. Consulta el para mantenerte al tanto de las novedades, o contacta a soporte si tienes sugerencias.