LunaPay® · Documentación

De tu primer cobro a una integración propia.

Descargar OpenAPI 3.1

Revisado el 19/09/2026

Webhooks verificados

Tu endpoint recibe eventos; debe verificar su firma y tolerar reintentos.

Ejemplos para ejecutar en tu servidor con datos propios de sandbox. Las claves nunca se incluyen en el frontend. Esta documentación no habilita operaciones live.

Recepción segura

Configurá un endpoint HTTPS público desde el panel autorizado. Conservá el cuerpo crudo. LunaPay-Event-Id identifica el evento y LunaPay-Signature contiene t y v1. La firma HMAC-SHA256 cubre eventId.timestamp.rawBody; rechazá diferencias de más de 300 segundos.

Verificar antes de procesar

El ejemplo rechaza cabeceras ausentes, firmas inválidas y timestamps no numéricos o vencidos. Después de verificar, deduplicá el ID y aplicá el cambio dentro de una transacción durable; respondé 2xx después de persistir.

Ejemplo de servidor
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody, headers, secret, now = Date.now()) {
  const id = headers.get('lunapay-event-id');
  const signature = headers.get('lunapay-signature');
  if (!id || !signature || !secret) return false;
  const match = /^t=(\d{1,12}),v1=([a-f0-9]{64})$/.exec(signature);
  if (!match) return false;
  const timestamp = Number(match[1]);
  if (!Number.isSafeInteger(timestamp) ||
      Math.abs(now / 1000 - timestamp) > 300) return false;
  const expected = createHmac('sha256', secret)
    .update(id + '.' + match[1] + '.' + rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(match[2], 'hex'));
}

Reintentos y conciliación

Las entregas pueden repetirse. Los replays conservan el ID del evento. No se promete entrega exactamente una vez. Un evento de factura, pago o retiro informa objetos distintos; procesalos por separado. La configuración interna de endpoints no es un recurso público /v1.

Contrato de desarrollo · fuente: Payments · 9f82d06

Siguiente guíaReferencia de recursos