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 una API key y puede tener un webhook.

El flujo general es:

1. Captura la tarjeta del cliente una sola vez con un link de colección (una página alojada por Zelta Pay que guarda la tarjeta con el procesador de tarjetas activo de tu cuenta — NMI o Emetec). Zelta Pay crea un cliente — no se cobra nada. El cliente registra qué procesador guardó su tarjeta, y sus cobros posteriores se hacen con 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. El bin y el vencimiento solo llegan en este webhook: las respuestas de la API no los incluyen.
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

Usa siempre 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 se procesan con las credenciales de sandbox de tu procesador, así que no mueven dinero real.

Usa el mismo entorno en todo el flujo

Los clientes no guardan en qué entorno se capturó su tarjeta: cada cargo o suscripción usa las credenciales del entorno que indique su propio isTest. Una tarjeta capturada con isTest: true debe cobrarse y suscribirse también con isTest: true (y una de producción, con isTest: false).

El modelo de proyectos

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

• 1 proyecto = 1 API key + 1 webhook (opcional). La API key autentica tus solicitudes y el webhook recibe los eventos del proyecto. Regenerar la API key invalida la anterior de inmediato, y la llave completa solo se muestra al crearla o regenerarla.
• Los clientes, suscripciones y cargos que crees viven dentro del proyecto y solo son accesibles con la API key de ese proyecto.
• La API key del proyecto también sirve en , limitada a los links del proyecto: los creados con esa API key. Los links creados desde el dashboard o con la API key de otro proyecto no aparecen, y obtenerlos o cancelarlos responde 404 con ERR_PAYMENT_LINK_NOT_FOUND (ver ).
• 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,
  "message": "...",
  "error": {
    "code": "ERR_..."
  },
  "timestamp": "2026-06-04T00:00:00.000Z"
}

Los errores de validación (400) usan otro formato, con la lista error.issues y sin message ni error.code; y un 429 por rate limit tiene cuerpo en texto plano. Consulta la .

Los montos siempre se expresan en centavos (entero). El monto de un link de pago de cliente va de 100 a 1000000 centavos ($1.00 a $10,000.00); el de un cargo o una suscripción es el precio del producto por la cantidad.

Límites y convenciones

• Rate limit: 60 solicitudes por ventana fija de 60 segundos por API key, compartidas con los demás endpoints /v1 (ver )
• Paginación: lim de 1 a 100 (default 10) y off; los listados se ordenan del más reciente al más antiguo y traen total
• IDs: cadenas numéricas sin prefijo; los productCode tienen el formato prod_ + 10 caracteres
• Cargos y clientes: devuelven siempre los campos de su objeto, el y el (el cliente dentro de una suscripción o de expand=customer es el mismo objeto). En sus listados, un fields con un campo fuera del objeto devuelve 400 con ERR_INVALID_FIELDS, y un expand no admitido devuelve 400 con ERR_INVALID_RELATIONS
• Errores de autenticación: 401 ERR_API_KEY_MISSING, 404 ERR_ACCOUNT_API_KEY_NOT_FOUND, 403 ERR_API_KEY_NOT_PROJECT_SCOPED (API key de la cuenta en lugar de la del proyecto), 403 ERR_PROJECT_INACTIVE y 403 ERR_ACCOUNT_SUSPENDED
• Webhooks: los eventos customer.*, charge.*, subscription.*, invoice.* y payment_link.rejected se envían solo al webhook del proyecto (si el proyecto no tiene uno activo, no se envían); payment.success, payment.failed y receipt.created usan el webhook de la cuenta como respaldo. Consulta

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