Venta de producto digital

Escenario: una web vende el ebook "UX en 30 días" a USD 19 y quiere que cada compra genere un pedido único (ORD-xxxx), se confirme por webhook y quede conciliada. El recibo y la factura se los envía Polar (el Merchant of Record) al comprador por email.

1. Crea la plantilla (una sola vez)

curl https://api.vexorpay.com/api/v1/payment-links \
  -X POST \
  -H "Authorization: Bearer vxp_live_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 19, "title": "Ebook UX en 30 días", "reference": "CATALOGO-UX" }'

Guardas el id del link, p. ej. 66f1c1e2c8a4b0d1f2e3a4b5.

2. Alguien compra → checkout único por pedido

Cuando tu cliente inicia la compra, llamas al checkout con la referencia del pedido y el email del comprador. Cada llamada crea una sesión de checkout de Polar nueva (no usa Idempotency-Key), así que guarda la URL si el cliente vuelve a intentar con el mismo pedido:

curl https://api.vexorpay.com/api/v1/payment-links/66f1c1e2c8a4b0d1f2e3a4b5/checkout \
  -X POST \
  -H "Authorization: Bearer vxp_live_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORD-1001",
    "customer_email": "cliente@mail.com",
    "metadata": { "userId": "u_42" }
  }'

Respuesta:

{
  "provider": "polar",
  "polarCheckoutId": "8f6c1d2e-...",
  "price_id": null,
  "seats": null,
  "checkoutUrl": "https://buy.polar.sh/polar_c_...",
  "expiresAt": "2026-01-02T13:00:00.000Z"
}

Redirige al cliente a ese checkoutUrl. La venta recién existe cuando el cliente paga: llega como una orden (GET /api/v1/orders) y con el webhook payment.completed.

3. El servidor del vendedor recibe el webhook

Al confirmarse el pago, vexorpay hace POST a tu endpoint configurado en Configuración → Webhooks, con headers vexorpay-Signature y vexorpay-Event-Id:

{
  "id": "evt_1001",
  "type": "payment.completed",
  "created": "2026-01-02T12:05:00.000Z",
  "data": {
    "charge": {
      "id": "67f1c1e2c8a4b0d1f2e3a4b5",
      "provider": "polar",
      "reference": "CATALOGO-UX",
      "amountCents": 1900,
      "currency": "usd",
      "status": "paid",
      "sandbox": false,
      "refundedCents": 0,
      "paidAt": "2026-01-02T12:05:00.000Z"
    },
    "payment_link": {
      "id": "66f1c1e2c8a4b0d1f2e3a4b5",
      "slug": "a1b2c3d4e5",
      "title": "Ebook UX en 30 días",
      "reference": "CATALOGO-UX"
    }
  }
}

Tu servidor:

1. Verifica la firma (HMAC-SHA256 del body crudo con tu secreto; comparación en tiempo constante).
2. Deduplica por id (guardas evt_1001 como procesado).
3. Consulta la venta (GET /api/v1/orders/{charge.id}) para ver el email del comprador, el link y los montos, y recién entonces marca el pedido como pagado y envía el ebook por email.

charge.id es el id de la venta (la orden de Polar) y charge.reference es la referencia del link. Para asociar la venta con tu pedido usa el customerEmail y el paymentLinkId de la orden.

4. Verificación a demanda (por si se perdió el webhook)

Siempre puedes preguntar por la venta puntual:

curl https://api.vexorpay.com/api/v1/orders/67f1c1e2c8a4b0d1f2e3a4b5 \
  -H "Authorization: Bearer vxp_live_tu_clave"

O listar el histórico de eventos con el mismo evt_ que te hubiera llegado por webhook:

curl "https://api.vexorpay.com/api/v1/events?type=payment.completed&created[gte]=2026-01-02T00:00:00.000Z" \
  -H "Authorization: Bearer vxp_live_tu_clave"

5. Saldo y contabilidad

curl https://api.vexorpay.com/api/v1/balance \
  -H "Authorization: Bearer vxp_live_tu_clave"

curl "https://api.vexorpay.com/api/v1/orders?status=paid" \
  -H "Authorization: Bearer vxp_live_tu_clave"

curl "https://api.vexorpay.com/api/v1/payouts" \
  -H "Authorization: Bearer vxp_live_tu_clave"

Resumen del flujo