Referencia API

Documentación completa de la API REST de Zelta Pay. Esta referencia cubre todos los endpoints, formatos de datos, códigos de error y convenciones de la API.

URL Base

https://api-pay.zelta.dev

Todas las solicitudes deben usar HTTPS. Las solicitudes HTTP serán rechazadas.

Versionamiento

La API usa versionamiento por ruta. La versión actual es v1:

https://api-pay.zelta.dev/v1/

Todas las rutas de endpoints incluyen el prefijo /v1/. Cambios que rompen compatibilidad se realizarán en nuevas versiones.

Autenticación

Todas las solicitudes requieren el header X-API-Key:

http

X-API-Key: tu-api-key-aqui

Consulta la para obtener tu clave y ver ejemplos de implementación.

Rate Limiting

60 solicitudes por minuto por API key
Ventana deslizante de 1 minuto
Headers de respuesta: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset
Al exceder el límite: 429 Too Many Requests con código ERR_RATE_LIMIT_EXCEEDED

Formato de respuesta

Respuesta exitosa

json

{
  "success": true,
  "data": { ... },
  "message": "Descripción de la operación",
  "timestamp": "2026-03-13T10:30:00.000Z"
}

Respuesta de error

json

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION_FAILED",
    "message": "Descripción del error",
    "details": [...]
  },
  "timestamp": "2026-03-13T10:30:00.000Z"
}

Códigos de estado HTTP

Código	Descripción	Uso
`200`	OK	Solicitud exitosa (GET, PATCH)
`201`	Created	Recurso creado exitosamente (POST)
`400`	Bad Request	Datos de solicitud inválidos o faltantes
`401`	Unauthorized	API key faltante o inválida
`403`	Forbidden	Cuenta suspendida o sin permisos
`404`	Not Found	Recurso no encontrado
`409`	Conflict	Conflicto de estado (ej. cancelar un link ya completado)
`429`	Too Many Requests	Rate limit excedido
`500`	Internal Server Error	Error interno del servidor

Códigos de error

Autenticación

Código	HTTP Status	Descripción
`ERR_MISSING_API_KEY`	401	No se incluyó el header `X-API-Key`
`ERR_API_KEY_NOT_FOUND`	404	La API key no existe o fue revocada
`ERR_ACCOUNT_SUSPENDED`	403	La cuenta está suspendida
`ERR_RATE_LIMIT_EXCEEDED`	429	Se superó el límite de solicitudes

Validación

Código	HTTP Status	Descripción
`ERR_VALIDATION_FAILED`	400	Los datos no pasan la validación
`ERR_INVALID_AMOUNT`	400	Monto fuera del rango permitido (100-1000000)
`ERR_METADATA_VALIDATION`	400	Metadata excede límites (20 keys o 8192 bytes)

Lógica de negocio

Código	HTTP Status	Descripción
`ERR_NO_ACTIVE_PAYMENT_PROVIDER`	400	No hay proveedor de pagos activo configurado
`ERR_INACTIVE_PAYMENT_METHOD`	400	El método de pago solicitado no está activo
`ERR_PAYMENT_LINK_NOT_FOUND`	404	El link de pago no existe
`ERR_INVALID_STATE_TRANSITION`	409	El link no puede cambiar al estado solicitado

Endpoints

Links de pago

Método	Ruta	Descripción
`GET`	`/v1/payment-links`	Listar links de pago
`POST`	`/v1/payment-links`	Crear un link de pago
`GET`	`/v1/payment-links/{hashUrl}`	Obtener un link de pago
`PATCH`	`/v1/payment-links/{hashUrl}/cancel`	Cancelar un link de pago

API de Integración (proyectos)

Estos endpoints requieren una API key ligada a un proyecto. Consulta la .

Método	Ruta	Descripción
`GET`	`/v1/products`, `/v1/products/{productCode}`	Consultar el catálogo de productos
`GET` `POST`	`/v1/customers`, `/v1/customers/{id}`, `/v1/customers/{id}/vault`	Gestionar clientes y su método de pago
`POST`	`/v1/collections/links`, `/v1/collections/payment-links`	Links de colección y de pago-cliente
`POST` `GET` `PATCH`	`/v1/subscriptions`, `/v1/subscriptions/{id}/...`	Crear y administrar suscripciones
`POST` `GET`	`/v1/charges`, `/v1/charges/{id}`	Cobros únicos a clientes vaulteados

Paginación

Los endpoints que devuelven listas soportan paginación con los parámetros:

Parámetro	Tipo	Default	Descripción
`lim`	`integer`	`10`	Cantidad de resultados por página (máx. 100)
`off`	`integer`	`0`	Número de resultados a saltar

Ejemplo

http

GET /v1/payment-links?lim=20&off=40

La respuesta incluye el campo total para calcular la paginación:

json

{
  "success": true,
  "data": {
    "paymentLinks": [...],
    "total": 150
  }
}

Tipos de datos

Montos

Todos los montos se expresan en centavos (integer):

Valor	Equivalente
`100`	$1.00
`1500`	$15.00
`1000000`	$10,000.00

Rango permitido: 100 a 1000000 (es decir, $1.00 a $10,000.00).

Timestamps

Todas las fechas y horas usan formato ISO 8601 en UTC:

2026-03-13T10:30:00.000Z

Estados de un link de pago

Estado	Descripción
`pending`	Link creado, pendiente de pago
`processing`	Pago en curso, esperando la confirmación del proveedor
`completed`	Pago completado exitosamente
`expired`	Link expirado sin pago (3 días desde la creación)
`cancelled`	Link cancelado manualmente

Estados de una transacción

Estado	Descripción
`pending`	Transacción creada, aún sin resolver
`processing`	En curso; el resultado final se entregará por webhook
`paid`	Pago liquidado correctamente
`failed`	Pago rechazado o fallido
`unknown`	La conciliación se agotó sin respuesta definitiva; requiere revisión manual
`deferred`	Cargo aprobado sin mover dinero, diferido al próximo cobro (addons <$1 en NMI)

Métodos de pago

Valor	Descripción
`"yappy"`	Pago con Yappy
`"card"`	Pago con tarjeta

Metadata

El campo metadata permite almacenar datos personalizados en formato clave-valor:

Máximo 20 llaves por objeto
Máximo 8192 bytes de tamaño total
Los valores deben ser de tipo string
No almacenes datos sensibles (tarjetas, contraseñas, tokens)

json

{
  "metadata": {
    "orderId": "ORD-2026-0042",
    "source": "web-checkout",
    "userId": "usr_abc123"
  }
}

Webhooks

Zelta Pay envía notificaciones en tiempo real a tu servidor cuando ocurren eventos relevantes.

Eventos disponibles

Zelta Pay emite eventos para pagos de links (payment.success, payment.failed), comprobantes (receipt.created) y, cuando usas la , para cargos (charge.*), suscripciones (subscription.*), facturas (invoice.*) y clientes (customer.created), además del evento de prueba webhook.ping.

Consulta la lista completa y el payload de cada evento en la .

Seguridad

Cada webhook incluye headers de firma (Zeltapay-Signature y Zeltapay-Timestamp) para verificar la autenticidad del mensaje. La firma es un HMAC-SHA256 calculado sobre el string t={timestamp}.{body}.

Consulta las guías de webhooks para más detalles:

Modo de prueba

Usa el campo isTest: true al crear links de pago para probar tu integración sin procesar pagos reales. Los links de prueba se comportan igual que los de producción, pero no generan cobros.

Puedes filtrar links de prueba con el parámetro isTest al .

SDKs

Actualmente no hay SDKs oficiales. La API REST es compatible con cualquier lenguaje que soporte solicitudes HTTP. Consulta los para ver código en Node.js, Python, PHP, Cloudflare Workers y Hono.

Changelog

Consulta el para ver el historial de cambios de la API.

Soporte

Si tienes preguntas o necesitas ayuda con la integración:

Revisa la para empezar
Consulta los para ejemplos prácticos
Contacta a soporte desde tu

Referencia API ​

URL Base ​

Versionamiento ​

Autenticación ​

Rate Limiting ​

Formato de respuesta ​

Respuesta exitosa ​

Respuesta de error ​

Códigos de estado HTTP ​

Códigos de error ​

Autenticación ​

Validación ​

Lógica de negocio ​

Endpoints ​

Links de pago ​

API de Integración (proyectos) ​

Paginación ​

Ejemplo ​

Tipos de datos ​

Montos ​

Timestamps ​

Estados de un link de pago ​

Estados de una transacción ​

Métodos de pago ​

Metadata ​

Webhooks ​

Eventos disponibles ​

Seguridad ​

Modo de prueba ​

SDKs ​

Changelog ​

Soporte ​

Referencia API

URL Base

Versionamiento

Autenticación

Rate Limiting

Formato de respuesta

Respuesta exitosa

Respuesta de error

Códigos de estado HTTP

Códigos de error

Autenticación

Validación

Lógica de negocio

Endpoints

Links de pago

API de Integración (proyectos)

Paginación

Ejemplo

Tipos de datos

Montos

Timestamps

Estados de un link de pago

Estados de una transacción

Métodos de pago

Metadata

Webhooks

Eventos disponibles

Seguridad

Modo de prueba

SDKs

Changelog

Soporte