Dashboardventipay.com
Guías
Home

Inicio rápido

Crea tu primer checkout, recibe el pago por webhook y haz tu primer reembolso.

Inicio rápido

En esta guía cobrarás tu primera venta y la reembolsarás. Necesitas una API key secreta con los scopes checkouts:write, checkouts:read y refunds:write.

Todas las llamadas usan https://api.ventipay.com/v1 y los montos van en unidades menores de la moneda (para CLP, pesos). Empieza con tu key de test: el flujo es idéntico y no se cobra nada real (tarjetas de prueba).

1. Crea un checkout

Indica la moneda y los ítems. El total (amount) lo calcula el servidor a partir de los ítems — no lo envías tú.

curl https://api.ventipay.com/v1/checkouts \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "clp",
    "items": [
      { "name": "Polera oversize", "sku": "POL-042", "unit_price": 15990, "quantity": 2 },
      { "name": "Despacho", "unit_price": 3500, "quantity": 1 }
    ],
    "external_id": "orden-10442",
    "success_url": "https://mitienda.cl/pago/exito",
    "cancel_url": "https://mitienda.cl/pago/error"
  }'
{
  "id": "chk_oGGZr23beBw6IXvJ3SNK7d7E",
  "object": "checkout",
  "status": "unpaid",
  "currency": "clp",
  "amount": 35480,
  "subtotal": 35480,
  "original_amount": 35480,
  "items": [
    { "name": "Polera oversize", "sku": "POL-042", "unit_price": 15990, "quantity": 2, "total": 31980 },
    { "name": "Despacho", "sku": "", "unit_price": 3500, "quantity": 1, "total": 3500 }
  ],
  "external_id": "orden-10442",
  "expires_at": "2026-07-31T14:03:11.000Z",
  "url": "https://pay.ventipay.com/checkout/chk_oGGZr23beBw6IXvJ3SNK7d7E",
  "successful_object": null,
  "payment_id": null,
  "loan_id": null,
  "account_entry_id": null
}

2. Envía a tu cliente a la url

Redirígelo desde tu sitio, mándala por email o WhatsApp, o muéstrala como QR — la url es la página de pago completa. Ahí el cliente elige el medio de pago (según lo que tengas habilitado en tu comercio), confirma, y Venti lo redirige a tu success_url o cancel_url.

Si prefieres cobrar sin escribir código, un botón de pago te da un link reutilizable que genera un checkout por cada cliente.

3. Recibe el webhook checkout.paid

La redirección del navegador es solo UX: la fuente de verdad es el webhook. Configura tu endpoint en el Dashboard (o con la API de Webhooks) y escucha:

{
  "id": "evt_Qm2vX9pLkR4TnW8sHjD3fGa7",
  "type": "checkout.paid",
  "live": true,
  "data": {
    "id": "chk_oGGZr23beBw6IXvJ3SNK7d7E",
    "object": "checkout",
    "status": "paid",
    "amount": 35480,
    "paid_at": "2026-07-17T14:09:42.000Z",
    "successful_object": "payment",
    "successful_object_id": "pay_hK2mR8vQpL9wN4sJhT5yBc3d",
    "payment_id": "pay_hK2mR8vQpL9wN4sJhT5yBc3d",
    "external_id": "orden-10442"
  }
}
app.post('/webhooks/venti', (req, res) => {
  const event = req.body;
  if (event.type === 'checkout.paid') {
    // Marca la orden `event.data.external_id` como pagada
  }
  res.sendStatus(200);
});

4. Consulta el checkout expandido

Con expand[] traes en la misma llamada el objeto que lo pagó y el medio de pago usado:

curl "https://api.ventipay.com/v1/checkouts/chk_oGGZr23beBw6IXvJ3SNK7d7E?expand[]=payment&expand[]=payment_method" \
  -u sk_live_xxx:
{
  "id": "chk_oGGZr23beBw6IXvJ3SNK7d7E",
  "status": "paid",
  "successful_object": "payment",
  "payment": {
    "id": "pay_hK2mR8vQpL9wN4sJhT5yBc3d",
    "object": "payment",
    "status": "succeeded",
    "authorized": true,
    "captured": true,
    "amount": 35480,
    "fee": 1064,
    "settlement_amount": 35480,
    "settlement_currency": "clp"
  },
  "payment_method": {
    "id": "pm_Xk3mR7vQpL9wN2sJhT5yBc4d",
    "type": "kushki_cards",
    "brand": "visa",
    "last4": "4242"
  }
}

Si el cliente pagó en cuotas BNPL verás successful_object: "loan" y loan_id; si pagó con una cuenta de Cuentas Venti, successful_object: "account_entry" y account_entry_id.

5. Reembolsa

curl https://api.ventipay.com/v1/checkouts/chk_oGGZr23beBw6IXvJ3SNK7d7E/refund \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15990 }'

Si omites amount (o envías 0) se reembolsa el total disponible. Puedes hacer reembolsos parciales sucesivos hasta agotar el monto original; el checkout va acumulando refunded_amount y expone available_for_refund. Recibirás checkout.refunded cuando se procese.

❗

Los reembolsos en vivo requieren balance disponible suficiente en tu cuenta Venti: el monto se debita de tu balance para devolverlo al cliente.

¿Y el cliente?

Tu cliente ve una página de pago con tu marca, los ítems del checkout y los medios de pago habilitados de tu comercio. Paga, recibe su comprobante por email y vuelve a tu sitio por la success_url. Si pagas por link (email, QR, botón de pago), no necesita nada más que abrirlo.

Siguiente paso

Sigue con Ciclo de vida y dinero para entender cuándo llega el dinero a tu balance y qué comisiones se descuentan.

Updated 1 day ago