LunaPay® · Documentação

Da primeira cobrança à sua própria integração.

Baixar OpenAPI 3.1

Revisado em 19/09/2026

Webhooks verificados

Seu endpoint recebe eventos; verifique assinaturas e tolere reenvios.

Execute os exemplos no seu servidor com seus próprios dados de sandbox. Nunca inclua chaves no frontend. Esta documentação não habilita operações live.

Recepção segura

Configure endpoint HTTPS público pelo painel autorizado. Preserve o corpo bruto. LunaPay-Event-Id identifica o evento; LunaPay-Signature contém t e v1. HMAC-SHA256 assina eventId.timestamp.rawBody; rejeite diferenças superiores a 300 segundos.

Verifique antes de processar

O exemplo rejeita cabeçalhos ausentes, assinaturas inválidas e timestamps não numéricos ou vencidos. Depois, deduplique o ID e aplique alterações em transação durável; responda 2xx após persistir.

Exemplo 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'));
}

Reenvios e conciliação

Entregas podem se repetir. Replays mantêm o ID. Não se promete entrega exatamente uma vez. Eventos de fatura, pagamento e retirada descrevem objetos distintos; processe separadamente. A configuração interna de endpoints não é recurso público /v1.

Contrato de desenvolvimento · fonte: Payments · 9f82d06

Próximo guiaReferência de recursos