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 comprador recibe por email el recibo de su pago.

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 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:

{
  "checkoutId": "ch_4f8a2c9d1e7b",
  "reference": "ORD-1001",
  "price_id": null,
  "checkoutUrl": "https://…/checkout/ch_4f8a2c9d1e7b",
  "expiresAt": null
}

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",
  "sandbox": false,
  "data": {
    "object": {
      "id": "67f1c1e2c8a4b0d1f2e3a4b5",
      "paymentLinkId": "66f1c1e2c8a4b0d1f2e3a4b5",
      "subscriptionId": null,
      "checkoutId": "ch_4f8a2c9d1e7b",
      "reference": "ORD-1001",
      "metadata": { "userId": "u_42" },
      "status": "paid",
      "billingReason": "one_time",
      "currency": "usd",
      "subtotalCents": 1900,
      "taxCents": 0,
      "totalCents": 1900,
      "feeCents": 190,
      "feeBreakdown": {
        "vexorpay": { "amountCents": 151, "percent": 2.7, "fixedCents": 100 },
        "extras": [
          { "type": "cross_border", "amountCents": 29, "percent": 1.5 },
          { "type": "fraud_prevention", "amountCents": 7, "percent": null },
          { "type": "authentication", "amountCents": 3, "percent": null }
        ]
      },
      "netCents": 1710,
      "refundedCents": 0,
      "refundableCents": 1900,
      "customerEmail": "cliente@mail.com",
      "customerName": "Ana Pérez",
      "productName": "Ebook UX en 30 días",
      "sandbox": false,
      "createdAt": "2026-01-02T12:05:00.000Z"
    }
  }
}

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. Busca tu pedido por data.object.reference (ORD-1001), confirma que status sea paid y recién entonces márcalo como pagado y envía el ebook por email. Si quieres confirmar contra la API, consulta GET /api/v1/orders/{data.object.id}.

data.object es la venta completa: reference es la referencia del pedido que mandaste en el checkout, y feeCents (la comisión de vexorpay, con el procesamiento incluido) y netCents traen el desglose de lo que te queda.

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