Inicio rápido

En esta guía crearás un producto, un impuesto y un plan; suscribirás a un cliente; y verás el primer cobro y cómo se renueva. Necesitas una API key secreta con los scopes products:write, tax_rates:write, plans:write, subscriptions:write e invoices:read.

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

1. Crea el producto

curl https://api.ventipay.com/v1/products \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Membresía Premium",
    "currency": "clp",
    "price": 12990,
    "pricing_type": "recurrent"
  }'

{
  "id": "prod_kT2mWqLp9RxN4vJcHs8fB3dY",
  "object": "product",
  "active": true,
  "name": "Membresía Premium",
  "currency": "clp",
  "price": 12990,
  "pricing_type": "recurrent",
  "live": true
}

pricing_type: recurrent significa que se cobra en cada ciclo. Un producto one_time (ej. costo de activación) se cobraría solo en el primer cobro.

2. Crea el impuesto

En Chile los precios al consumidor ya incluyen IVA, así que lo típico es un impuesto inclusivo — se desglosa en la nota de venta pero no suma al total:

curl https://api.ventipay.com/v1/tax_rates \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "IVA",
    "percentage": 19,
    "inclusive": true,
    "jurisdiction": "CL"
  }'

{
  "id": "txr_Zw7pQm3KvT9xL2sRnJ4hYc6B",
  "object": "tax_rate",
  "active": true,
  "name": "IVA",
  "percentage": "19.00",
  "inclusive": true,
  "jurisdiction": "CL",
  "live": true
}

Con inclusive: false el impuesto se agregaría sobre el subtotal en cada cobro.

3. Crea el plan

El plan junta productos, impuestos y frecuencia, y te da un link compartible:

curl https://api.ventipay.com/v1/plans \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium mensual",
    "currency": "clp",
    "interval": "1month",
    "billing_cycle_anchor": "1",
    "default_products": [{ "id": "prod_kT2mWqLp9RxN4vJcHs8fB3dY", "quantity": 1 }],
    "default_tax_rates": [{ "id": "txr_Zw7pQm3KvT9xL2sRnJ4hYc6B" }]
  }'

{
  "id": "pl_Xv4nRq8LwK2mT7pJcY3sZb9D",
  "object": "plan",
  "active": true,
  "name": "Premium mensual",
  "currency": "clp",
  "interval": "1month",
  "billing_cycle_anchor": "1",
  "amount": 12990,
  "subtotal": 12990,
  "proration_behavior": "create_prorations",
  "trial_days": 0,
  "url": "https://pay.ventipay.com/plan/pl_Xv4nRq8LwK2mT7pJcY3sZb9D",
  "live": true
}

Publica esa url donde quieras (tu sitio, un email, un QR): cada cliente que la abra y se suscriba genera su propia suscripción con esta configuración. Con billing_cycle_anchor: "1" todos se cobran el día 1; su primer cobro es proporcional a los días que queden del mes.

4. Suscribe a un cliente específico

Si en lugar del link genérico quieres suscribir a un cliente, crea la suscripción directamente. Basta su email — si no existe en Venti, se crea:

curl https://api.ventipay.com/v1/subscriptions \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium mensual",
    "currency": "clp",
    "interval": "1month",
    "billing_cycle_anchor": "1",
    "customer_email": "[email protected]",
    "default_products": [{ "id": "prod_kT2mWqLp9RxN4vJcHs8fB3dY", "quantity": 1 }],
    "default_tax_rates": [{ "id": "txr_Zw7pQm3KvT9xL2sRnJ4hYc6B" }]
  }'

{
  "id": "sub_Mh6tKq2WvR9pX4nL8sJcZ3fB",
  "object": "subscription",
  "status": "incomplete",
  "name": "Premium mensual",
  "currency": "clp",
  "interval": "1month",
  "billing_cycle_anchor": "1",
  "amount": 12990,
  "subtotal": 12990,
  "customer_id": "cus_WBRjn77K2eFdAoU7gKibtkb3",
  "default_payment_method_id": null,
  "current_period_starts_at": null,
  "current_period_ends_at": null,
  "cycles": 0,
  "trial_days": 0,
  "url": "https://pay.ventipay.com/subscription/sub_Mh6tKq2WvR9pX4nL8sJcZ3fB",
  "live": true
}

La suscripción nace incomplete: existe, pero no cobra nada hasta que el cliente la autorice.

5. El cliente autoriza

Comparte la url de la suscripción. El cliente abre la página de pago de Venti, inscribe su tarjeta y confirma. En ese momento se cobra el primer período y la suscripción pasa a active (o a trialing si definiste trial_days, sin cobro inicial).

Si ya tienes la tarjeta del cliente inscrita (por ejemplo, la capturaste con un Setup Intent), puedes evitar el paso del link: asigna el medio de pago con PUT /subscriptions/{id} (default_payment_method_id) y llama POST /subscriptions/{id}/start. El inicio por API requiere una tarjeta — un medio de pago de autorización síncrona.

6. Observa el primer cobro

curl "https://api.ventipay.com/v1/invoices?subscription_id=sub_Mh6tKq2WvR9pX4nL8sJcZ3fB" \
  -u sk_live_xxx:

{
  "object": "list",
  "data": [
    {
      "id": "inv_Qp8vNm4XwK7rT2sLcJ9hZf3G",
      "object": "invoice",
      "status": "paid",
      "paid": true,
      "amount": 7124,
      "subtotal": 7124,
      "tax": 1354,
      "tax_amounts": [
        { "name": "IVA", "percentage": 19, "inclusive": true, "amount": 1354 }
      ],
      "lines": [
        { "product_id": "prod_kT2mWqLp9RxN4vJcHs8fB3dY", "name": "Membresía Premium", "price": 12990, "quantity": 1, "total": 12990 }
      ],
      "proration": { "prorate": true, "factor": 0.5483, "amount": 5866 },
      "period_starts_at": "2026-07-15T00:00:00.000Z",
      "period_ends_at": "2026-08-01T00:00:00.000Z",
      "subscription_id": "sub_Mh6tKq2WvR9pX4nL8sJcZ3fB",
      "successful_payment_id": "pay_Ts3wLq9KvM6xR8pN2cJhY4fZ",
      "collection_method": "automatic",
      "paid_at": "2026-07-15T14:22:38.000Z"
    }
  ]
}

Fíjate en dos cosas:

El primer período es parcial (15 de julio al 1 de agosto, por el ancla en el día 1) y el monto fue prorrateado: proration.factor ≈ 0.55 del precio del plan. Ese comportamiento lo controla proration_behavior.
successful_payment_id referencia un pago normal de Venti (pay_...), con subscription_id e invoice_id. Ese pago abona a tu balance menos las comisiones estándar, como cualquier venta.

La suscripción ahora se ve así:

curl https://api.ventipay.com/v1/subscriptions/sub_Mh6tKq2WvR9pX4nL8sJcZ3fB -u sk_live_xxx:

{
  "id": "sub_Mh6tKq2WvR9pX4nL8sJcZ3fB",
  "status": "active",
  "current_period_starts_at": "2026-07-15T00:00:00.000Z",
  "current_period_ends_at": "2026-08-01T00:00:00.000Z",
  "next_renewal_at": "2026-08-01T00:00:00.000Z",
  "cycles": 1,
  "default_payment_method_id": "pm_Kc9rXw2LqN7vT4mJ8sZhP3fY"
}

7. La renovación es automática

No hay nada más que hacer. El 1 de agosto Venti genera la nota de venta del nuevo período (esta vez por los 12990 completos), la carga a la tarjeta y — si todo sale bien — la suscripción sigue active con cycles: 2 y el período corrido un mes. Recibirás los webhooks invoice.created, invoice.paid y los payment.* de siempre (Webhooks y conciliación).

Si el cobro falla, la suscripción pasa a past_due y comienzan los reintentos — el detalle está en Ciclo de vida.

¿Y el cliente?

El cliente recibe un email al activarse su suscripción, otro si un cobro queda pendiente, y puede ver y administrar sus suscripciones (cambiar tarjeta, pausar o cancelar, si tu comercio lo permite) desde la misma página de la suscripción y su billetera Venti — sin apps nuevas ni contraseñas tuyas.