Dashboardventipay.com
Guías
Home

Inicio rápido

Tu primera venta en cuotas: del checkout de siempre al préstamo autorizado y sus cuotas.

Inicio rápido

En esta guía verás el ciclo completo de una venta en cuotas. Necesitas una API key secreta con los scopes loans:read e installments:read (más loans:write para crear préstamos directos y refunds:write para devolver), y tener programas de cuotas configurados en tu comercio.

Todas las llamadas usan https://api.ventipay.com/v1 y los montos van en unidades menores de la moneda (para CLP, pesos).

1. Cobra con un checkout como siempre

No hay nada nuevo que integrar: crea el checkout igual que para cualquier pago.

curl https://api.ventipay.com/v1/checkouts \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 79990,
    "currency": "clp",
    "success_url": "https://mitienda.cl/gracias"
  }'

Cuando el cliente abre el checkout y elige una tarjeta compatible, ve la opción de pagar en cuotas junto a los programas disponibles (cantidad de cuotas, montos, interés si aplica). Al confirmar:

  1. Venti crea el Loan vinculado al checkout y evalúa el crédito del cliente en el acto.
  2. Si lo aprueba, cobra la primera cuota hoy con la tarjeta del cliente (con 3D Secure si corresponde).
  3. El préstamo queda autorizado y el checkout, pagado.

Si el crédito se rechaza, el cliente ve el error y puede pagar con otro medio; el checkout sigue vigente.

2. Observa el checkout pagado

curl https://api.ventipay.com/v1/checkouts/chk_oGGZr23beBw6IXvJ3SNK7d7E \
  -u sk_live_xxx:
{
  "id": "chk_oGGZr23beBw6IXvJ3SNK7d7E",
  "object": "checkout",
  "status": "paid",
  "amount": 79990,
  "currency": "clp",
  "successful_object": "loan",
  "loan_id": "loan_mK4vR7xT3nQ8sYbF6dAoU2Wp",
  "payment_id": null,
  "paid_at": "2026-07-17T14:05:22.000Z"
}

La única diferencia con un pago directo: successful_object es "loan" y viene loan_id en lugar de payment_id.

3. Consulta el préstamo y sus cuotas

curl "https://api.ventipay.com/v1/loans/loan_mK4vR7xT3nQ8sYbF6dAoU2Wp?expand[]=installments" \
  -u sk_live_xxx:
{
  "id": "loan_mK4vR7xT3nQ8sYbF6dAoU2Wp",
  "object": "loan",
  "status": "succeeded",
  "authorized": true,
  "authorized_at": "2026-07-17T14:05:22.000Z",
  "amount": 79990,
  "currency": "clp",
  "fee": 3200,
  "installment_program": "cl_1n2l_bw",
  "installments_plan": { "type": "bnpl", "count": 3, "interval": "biweek" },
  "interest_amount": 0,
  "interest_rate": 0,
  "surcharge_amount": 0,
  "surcharge_tax": 0,
  "refunded": false,
  "refunded_amount": 0,
  "available_for_refund": 79990,
  "checkout_id": "chk_oGGZr23beBw6IXvJ3SNK7d7E",
  "customer_id": "cus_WBRjn77K2eFdAoU7gKibtkb3",
  "payout_id": null,
  "url": "https://pay.ventipay.com/loan/loan_mK4vR7xT3nQ8sYbF6dAoU2Wp",
  "installments": [
    { "id": "inst_Qm2vX9pLkR4TnW8sHjD3fGa7", "number": 1, "amount": 26664, "status": "paid", "paid_at": "2026-07-17T14:05:22.000Z", "due_at": "2026-07-17T14:05:11.000Z" },
    { "id": "inst_Wb8sHjD3fGa7Qm2vX9pLkR4T", "number": 2, "amount": 26663, "status": "open", "paid_at": null, "due_at": "2026-08-01T04:00:00.000Z" },
    { "id": "inst_Ga7Qm2vX9pLkR4TnW8sHjD3f", "number": 3, "amount": 26663, "status": "open", "paid_at": null, "due_at": "2026-08-16T04:00:00.000Z" }
  ]
}

La cuota 1 quedó paid en el momento de la autorización; las restantes se cobrarán solas en su due_at. También puedes listar cuotas directamente con GET /installments?customer_id=cus_... o consultar una con GET /installments/{id}.

4. Crea un préstamo directo (sin checkout)

Si quieres ofrecer financiamiento fuera de un checkout (por ejemplo, por un canal propio), crea el préstamo directamente — basta el email del cliente y, si no existe en Venti, se crea:

curl https://api.ventipay.com/v1/loans \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 129990,
    "currency": "clp",
    "customer_email": "[email protected]",
    "description": "Orden #4512",
    "success_url": "https://mitienda.cl/gracias"
  }'

Comparte la url de la respuesta (https://pay.ventipay.com/loan/{id}): es la página de pago del préstamo, donde el cliente elige su programa de cuotas y completa el financiamiento igual que en un checkout.

5. Devuelve una venta en cuotas

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

Omite amount (o envía 0) para devolver todo lo disponible. Venti cancela las cuotas pendientes y le devuelve al cliente lo que ya pagó; el monto se descuenta de tu balance, porque tú recibiste el total por adelantado. Detalles en cuotas y cobranza.

¿Y el cliente?

Tu cliente paga la primera cuota en el momento, con su tarjeta de siempre. Después, Venti se encarga: le cobra automáticamente cada cuota en su vencimiento, le avisa por email antes y después de cada vencimiento, y le da su billetera Venti (pay.ventipay.com/wallet) para ver sus cuotas y pagarlas manualmente cuando quiera — incluso con otros medios de pago.

Siguiente paso

Sigue con cuotas y cobranza para entender exactamente cuándo llega tu abono y qué pasa con las cuotas del cliente.

Updated 1 day ago