← Documentación

API LunaPay · v1

Cobros para tu sitio web

Creá un checkout desde tu servidor y recibí la confirmación del pago en tu sistema.

1. Prepará tu cuenta Premium

Necesitás un contrato Premium Compliance vigente, comercio aprobado, catálogo y proveedores habilitados para la moneda y el ambiente. Las comisiones y liquidaciones son las de tu contrato.

En el panel, ingresá a API y webhooks. Con MFA, emití una clave con los permisos mínimos: customers:write, products:write, prices:write, checkout-sessions:write y payments:read para el ejemplo completo. Si ya tenés catálogo y cliente, bastan los dos últimos.

Guardá la clave en variables privadas de tu servidor. Las claves lp_sandbox_ y lp_live_ fijan el comercio y ambiente; no se envían desde JavaScript público ni se intercambian entre ambientes. Configurá el endpoint HTTPS y su secreto de webhooks en el panel.

2. Creá el checkout

Creá cliente, producto y precio desde el panel o /v1/customers, /v1/products y /v1/prices. Los importes se expresan como strings en unidades menores: 10000 equivale a ARS 100,00. Elegí precios y cantidades en tu servidor a partir del pedido validado.

const response = await fetch(process.env.LUNAPAY_ORIGIN + "/v1/checkout-sessions", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.LUNAPAY_API_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "pedido-00001-checkout"
  },
  body: JSON.stringify({
    reference: "pedido-00001", contractId: "CONTRATO_UUID",
    customerId: "CLIENTE_UUID", currency: "ARS",
    items: [{ priceId: "PRECIO_UUID", quantity: 1 }],
    presentation: { successUrl: "https://tu-sitio.example/gracias" }
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.code);
// Desde tu servidor, redirigí al comprador a result.data.url.
// Guardá result.data.id junto al pedido. El retorno no confirma el pago.

La respuesta contiene data.id, amountMinor, currency, url y expiresAt. El enlace es privado: no lo publiques ni lo registres en analítica. El comprador acepta las condiciones en el checkout alojado y elige un medio disponible.

Usá una Idempotency-Key de 8–200 caracteres por operación. Repetí la misma clave y cuerpo cuando haya un timeout. Un cuerpo diferente con la misma clave devuelve conflicto. No generes otro cobro para resolver un resultado incierto.

3. Confirmá desde tu servidor

Escuchá payment.paid. El JSON incluye id, type, environment y resource.id. Verificá LunaPay-Signature antes de interpretar el cuerpo: HMAC-SHA256 del texto exacto eventId.timestamp.body, usando LunaPay-Event-Id y el secreto del endpoint. El encabezado tiene formato t=timestamp,v1=hex. Compará en tiempo constante y rechazá una diferencia de tiempo mayor a cinco minutos.

Guardá el identificador del evento con una restricción única y actualizá el pedido en la misma transacción. Las entregas pueden repetirse o llegar fuera de orden. Respondé 2xx después de persistir el evento; usá una cola durable para procesarlo. En caso de fallos, LunaPay reintenta y permite replay desde el panel.

Consultá GET /v1/payments/ID con payments:read para verificar estado, referencia, moneda e importe contra tu pedido. Por compatibilidad, data es un array también al consultar un ID; un resultado vacío significa que no hay un pago visible con ese ID. Solo el estado paid confirma el pago; no confundas processing con confirmación ni held o una devolución con saldo disponible.

El retorno a tu sitio no prueba un cobro. Usá eventos posteriores y consulta de estado para devoluciones y disputas. POST /v1/refunds solicita una devolución sujeta al contrato; su confirmación es asíncrona.

Errores y puesta en marcha

Los errores devuelven error.code, message y requestId. 400/415: corregí la solicitud; 401/403: revisá clave, permisos, contrato y habilitación; 409: resolvé el conflicto; 429: esperá antes de reintentar. Ante 5xx o timeout, conservá la clave idempotente y consultá el estado.

Probá primero en sandbox: pago confirmado, cancelación, fallo, timeout, evento duplicado, firma inválida y devolución. La disponibilidad de una API o una clave no habilita pagos live; cada proveedor y circuito requiere aprobación.

El repositorio incluye scripts/cobros-web.ts, ejecutable con npx tsx, y src/integrations/webhook-signature.ts como referencia verificable. La guía operativa docs/cobros-web.md detalla las variables y la ejecución.

Términos, privacidad y reclamos