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:

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

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

Respuesta de error

{
  "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-200000)
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

Método	Ruta	Descripción	Documentació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

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

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

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

{
  "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
200000	$2,000.00

Rango permitido: 100 a 200000 (es decir, $1.00 a $2,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
completed	Pago completado exitosamente
expired	Link expirado sin pago (3 días desde la creación)
cancelled	Link cancelado manualmente

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)

{
  "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

• Pago completado
• Link expirado
• Link cancelado

Seguridad

Cada webhook incluye headers de firma (zeltapay-signature y zeltapay-timestamp) para verificar la autenticidad del mensaje.

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