API de Integración

La API de Integración permite que tu software incruste Zelta Pay como su motor de pagos. Todo se organiza en torno a un proyecto: cada proyecto tiene exactamente una API key y un webhook.

El flujo general es:

1. Captura la tarjeta del cliente una sola vez con un link de colección (un formulario alojado por el procesador de tarjetas activo de tu cuenta — NMI o Emetec). Zelta Pay tokeniza la tarjeta y crea un cliente — no se cobra nada. El token registra qué procesador la almacenó, de modo que todo cobro posterior se enruta automáticamente a ese mismo procesador.
2. Recibes el webhook customer.created con el id del cliente y los metadatos de facturación de la tarjeta (bin, exp, últimos 4, marca) para guardarlos en tu sistema.
3. Tu software mueve el dinero por API: suscripciones (POST /v1/subscriptions) para planes recurrentes — compuestos de uno o más productos del catálogo con cantidades (items) — y cargos (POST /v1/charges) para productos de pago único, como créditos independientes o addons que requieren una suscripción activa.

Todos los endpoints de estos recursos requieren tu API key de proyecto en el header X-API-Key.

Autenticación y URLs base

Todos los recursos de la API de Integración (products, customers, subscriptions, collections, charges) requieren una API key ligada a un proyecto. Incluye la clave en el header X-API-Key en cada solicitud.

X-API-Key: tu-api-key-de-proyecto

Las solicitudes solo se aceptan por HTTPS. La URL base es:

https://api-pay.zelta.dev

Todos los endpoints se versionan con el prefijo /v1/.

Modo sandbox / pruebas

No existe una URL separada para pruebas. Para operar en modo test usa la misma URL de producción y envía isTest: true en el cuerpo de la solicitud (al crear links de colección, cargos o suscripciones). Los recursos de prueba no procesan cobros reales.

El modelo de proyectos

Un proyecto es la unidad que conecta tu software con Zelta Pay:

• 1 proyecto = 1 API key + 1 webhook. La API key autentica tus solicitudes y el webhook recibe todos los eventos del proyecto.
• Los clientes, suscripciones y cargos que crees viven dentro del proyecto y solo son accesibles con la API key de ese proyecto.
• El catálogo de productos se gestiona por proyecto desde el dashboard.

Puedes crear y administrar tus proyectos desde la sección Proyectos del dashboard:

Al abrir un proyecto encontrarás su API key y su webhook, además de las pestañas para consultar sus productos, suscripciones, cargos, clientes y las trazas de entrega de webhooks:

Tipos de producto

Cada producto del catálogo se define por dos campos — paymentType (one_time o recurring) y, para los productos de pago único, requiresSubscription. Esos dos campos determinan qué es un producto y cómo se cobra:

paymentType	requiresSubscription	Es un…	Se cobra con
recurring	—	Plan — un item de suscripción facturado cada ciclo	(como item)
one_time	false	Producto independiente — una compra única, como créditos	, o un (productCode)
one_time	true	Addon — un cobro único que solo tiene sentido sobre un plan	— el cliente debe tener una suscripción activa en el proyecto; el cargo se vincula a ella (admite proración)

En otras palabras, un addon es simplemente un producto one_time marcado con requiresSubscription: true: no puede cobrarse por sí solo, únicamente contra un cliente que ya tenga una suscripción activa en el proyecto. Un producto one_time sin ese flag es independiente y puede cobrarse en cualquier momento.

El catálogo de productos se gestiona desde el dashboard

Los productos (planes, addons, créditos) se crean y editan solo desde el dashboard (proyecto → Productos). La API de Integración es de solo lectura sobre el catálogo: usa / GET /v1/products/:productCode para consumir los productos existentes por su productCode.

Formato de respuesta

Todas las respuestas siguen una estructura JSON consistente.

Éxito:

{
  "success": true,
  "data": { },
  "message": "...",
  "timestamp": "2026-06-04T00:00:00.000Z"
}

Error:

{
  "success": false,
  "error": {
    "code": "ERR_...",
    "message": "..."
  },
  "timestamp": "2026-06-04T00:00:00.000Z"
}

Los montos siempre se expresan en centavos (entero). El monto máximo de un link o pago es 1000000 centavos = $10,000.00.

Las páginas de esta sección

• — consulta el catálogo (solo lectura).
• — crea clientes y adjunta tarjetas vaulteadas.
• — captura la tarjeta (y opcionalmente cobra) con una página alojada.
• — planes recurrentes, items, dunning y facturas.
• — cobros de pago único, estados, proración e idempotencia.

Siguientes pasos

• — el primer paso es capturar y guardar la tarjeta del cliente
• — genera la página alojada de captura
• — cómo recibes los resultados