Inicio Rápido

Bienvenido a la API de Zelta Pay. Esta guía te ayudará a crear tu primer link de pago y entender los fundamentos de nuestra API.

¿Prefieres usar el dashboard?

Si prefieres crear links de pago sin código, consulta la guía del y .

Requisitos previos

Antes de comenzar, asegúrate de tener:

• Una cuenta de Zelta Pay
• Al menos un método de pago activo en . Para los ejemplos de esta guía (isTest: true) necesitas credenciales de Sandbox
• Una API key (obtenida desde tu dashboard)
• Conocimiento básico de solicitudes HTTP
• Un entorno de desarrollo listo

Paso 1: Obtén tu API Key

1. Inicia sesión en tu
2. Abre API Key en el menú lateral (visible solo para los roles propietario y administrador)
3. En la tarjeta Nueva API key, escribe un alias descriptivo (ej. mi-app-produccion) y haz clic en Crear. El botón permanece deshabilitado hasta que la cuenta tenga un proveedor de pago activo
4. En la fila de la nueva llave, haz clic en Ver llave y luego en Copiar, y guárdala de forma segura

Buena práctica de seguridad

Nunca guardes API keys en el control de versiones. Usa variables de entorno o gestión segura de secretos.

Paso 2: Haz tu primera llamada a la API

Probemos tu API key listando tus links de pago existentes:

curl -X GET "https://api-pay.zelta.dev/v1/payment-links" \
  -H "X-API-Key: tu-api-key-aqui" \
  -H "Content-Type: application/json"

Paso 3: Crea tu primer link de pago

Ahora creemos un link de pago:

curl -X POST "https://api-pay.zelta.dev/v1/payment-links" \
  -H "X-API-Key: tu-api-key-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "concept": "Pago de prueba",
    "amount": 100,
    "customerName": "Juan Pérez",
    "isTest": true
  }'

Paso 4: Entiende la respuesta

Una respuesta exitosa se verá así:

{
  "success": true,
  "data": {
    "paymentLink": {
      "id": "7312345678901234567",
      "paymentLinkUrl": "https://pay.zelta.dev/Xk3v9Q_aB7mN2pL8rT4wYz1c",
      "customerName": "Juan Pérez",
      "concept": "Pago de prueba",
      "amount": 100,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "expiresAt": "2024-01-18T10:30:00.000Z",
      "status": "pending",
      "isTest": true,
      "requestCustomerEmail": true
    }
  },
  "message": "Payment link created successfully",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Campos clave de la respuesta

• paymentLinkUrl: La URL que tu cliente usará para pagar. Su último segmento es el hashUrl del link, que usas para o
• id: Identificador único del link de pago (una cadena numérica)
• status: Estado actual (siempre "pending" para links nuevos)
• expiresAt: Cuándo vence el link: 3 días después de crearlo, por defecto. Envía expiresInDays (de 1 a 60) para elegir otra vigencia; consulta

Paso 5: Gestiona el pago

Una vez que tengas la URL del link de pago, puedes:

1. Enviarlo a tu cliente por correo, SMS o mostrarlo en tu sitio web
2. Redirigirlo al portal de pago
3. Monitorear el estado llamando a la API o configurando webhooks

// Redirigir al cliente a la página de pago
window.location.href = result.data.paymentLink.paymentLinkUrl;

Paso 6: Configura webhooks (opcional)

Para recibir notificaciones en tiempo real cuando se completen los pagos:

1. Abre Webhooks en el menú lateral del dashboard (visible solo para los roles propietario y administrador)
2. En la tarjeta Nuevo webhook, escribe la URL de tu endpoint (debe ser una URL HTTPS pública) y haz clic en Crear. La cuenta tiene un solo webhook, y crearlo requiere un proveedor de pago activo
3. Copia el secreto de firma con Ver secreto
4. Haz clic en Enviar ping para enviar un webhook.ping firmado a tu endpoint

No hay selección de eventos: el webhook recibe todos los eventos de los links de la cuenta (payment.success, payment.failed, receipt.created...). Ignora los tipos que no manejes.

Implementación de verifySignature

Los ejemplos usan un helper verifySignature. Su implementación completa está en la guía de . Recuerda que la firma se recibe en el header Zeltapay-Signature con el formato t=<timestamp>, v1=<hmac>, y que el HMAC-SHA256 se calcula sobre el string t={timestamp}.{body} (incluyendo el prefijo t=).

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['zeltapay-signature'];
  const timestamp = req.headers['zeltapay-timestamp'];

  // Verificar firma (importante para seguridad)
  if (!verifySignature(req.body.toString(), timestamp, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const payload = JSON.parse(req.body);

  if (payload.type === 'payment.success') {
    console.log('Pago completado:', payload.transaction.amount);
    // Actualiza tu base de datos, envía correo de confirmación, etc.
  }

  res.status(200).json({ received: true });
});

Siguientes pasos

• — API keys y rate limiting
• — Opciones avanzadas y validación
• — Notificaciones de pago en tiempo real
• — Documentación completa de endpoints

Problemas comunes

401 Unauthorized

• Falta el header X-API-Key: asegúrate de incluirlo

404 Not Found (ERR_ACCOUNT_API_KEY_NOT_FOUND)

• La API key está mal copiada, se regeneró o se eliminó. Las API keys no tienen estado activo/inactivo
• Copia la llave vigente desde API Key → Ver llave en el dashboard

400 Bad Request

• Verifica que todos los campos requeridos estén incluidos (y que envíes Content-Type: application/json)
• Asegúrate de que el monto esté en centavos (ej. 100 = $1.00); el mínimo es 100
• Si el error es ERR_NO_ACTIVE_PAYMENT_PROVIDER, configura un método de pago para el entorno del link (sandbox para isTest: true)
• Confirma que el formato JSON sea correcto

429 Too Many Requests

• Has excedido el rate limit (60 solicitudes por ventana de 60 segundos por API key)
• Espera los segundos que indica el header Retry-After antes de hacer más solicitudes (el cuerpo es texto plano, no JSON)
• Considera implementar cola de solicitudes