Inicio rápido

En esta guía crearás un programa, emitirás una cuenta a un cliente y verás el ciclo completo de una compra. Necesitas una API key secreta con los scopes programs:write y financial_accounts:write, y tener la funcionalidad Cuentas habilitada 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. Crea un programa

El programa define las reglas de todas sus cuentas. El name es lo que tus clientes verán como el nombre de su cuenta.

curl https://api.ventipay.com/v1/programs \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "name": "VentiCard",
    "currency": "clp",
    "default_credit_limit": 100000,
    "max_credit_limit": 500000,
    "billing_anchor": "1",
    "grace_period_days": 10,
    "min_payment_type": "percentage",
    "min_payment_percentage": 25
  }'

Con billing_anchor: "1" los ciclos cierran el día 1 de cada mes. Si prefieres ciclos por días corridos, omite billing_anchor y usa billing_cycle_days (por defecto 30).

2. Emite una cuenta

Basta el email del cliente — si no existe en Venti, se crea y se asocia a tu comercio automáticamente:

curl https://api.ventipay.com/v1/financial_accounts \
  -u sk_live_xxx: \
  -H "Content-Type: application/json" \
  -d '{
    "program_id": "prog_bBgSHb7jRKky1FOFLtF06Nqj",
    "customer_email": "[email protected]",
    "credit_limit": 150000
  }'

{
  "id": "fa_jB6Lq69HecMiVIGmQ24q5nZ1",
  "object": "financial_account",
  "status": "active",
  "currency": "clp",
  "credit_limit": 150000,
  "posted_balance": 0,
  "held_amount": 0,
  "available": 150000,
  "customer_id": "cus_WBRjn77K2eFdAoU7gKibtkb3",
  "program_id": "prog_bBgSHb7jRKky1FOFLtF06Nqj"
}

Si omites credit_limit, la cuenta usa el default_credit_limit del programa. El cupo nunca puede superar el max_credit_limit del programa.

3. Cobra con la cuenta

No hay nada nuevo que integrar: crea checkouts como siempre. Cuando el titular de una cuenta abre el checkout, ve su cuenta como medio de pago (con su nombre de programa y su disponible), la elige y confirma con un código de verificación de 6 dígitos enviado a su email.

Al autorizarse el pago:

• El checkout queda paid con successful_object: "account_entry" y account_entry_id — sin payment_id, porque no se movió dinero real.
• Se registra un movimiento purchase en el libro mayor y el disponible de la cuenta baja.
• Recibes el webhook checkout.paid de siempre.

4. Consulta el libro mayor

curl "https://api.ventipay.com/v1/account_entries?financial_account_id=fa_jB6Lq69HecMiVIGmQ24q5nZ1" \
  -u sk_live_xxx:

{
  "object": "list",
  "data": [
    {
      "id": "ae_Qm2vX9pLkR4TnW8sHjD3fGa7",
      "object": "account_entry",
      "entry_type": "purchase",
      "direction": "debit",
      "amount": 45990,
      "currency": "clp",
      "balance_after": -45990,
      "sequence": 1,
      "checkout_id": "chk_oGGZr23beBw6IXvJ3SNK7d7E",
      "statement_id": null,
      "created_at": "2026-07-17T14:03:11.000Z"
    }
  ]
}

Cada movimiento indica su origen: checkout_id para compras, devoluciones y pagos; statement_id además, para los pagos de estados de cuenta. Puedes expandirlos (expand[]=checkout).

5. Devuelve una compra

Reembolsa el checkout con el endpoint normal:

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

En un checkout pagado con cuenta la devolución es instantánea: se registra un movimiento refund que restituye el cupo del cliente. No hay movimiento de dinero ni impacto en tu balance. Se admiten devoluciones parciales sucesivas hasta el monto original.

6. Administra la cuenta

# Ajustar el cupo (nunca bajo la deuda vigente, nunca sobre el máximo del programa)
curl -X PUT https://api.ventipay.com/v1/financial_accounts/fa_jB6L... \
  -u sk_live_xxx: -H "Content-Type: application/json" \
  -d '{ "credit_limit": 200000 }'

# Congelar (bloquea compras; la deuda sigue cobrándose)
curl -X PUT https://api.ventipay.com/v1/financial_accounts/fa_jB6L... \
  -u sk_live_xxx: -H "Content-Type: application/json" \
  -d '{ "status": "frozen" }'

# Cerrar (definitivo; requiere saldo cero)
curl -X PUT https://api.ventipay.com/v1/financial_accounts/fa_jB6L... \
  -u sk_live_xxx: -H "Content-Type: application/json" \
  -d '{ "status": "closed" }'

¿Y el cliente?

Tu cliente no necesita ninguna app nueva: paga en el checkout de Venti, recibe su estado de cuenta por email con un link de pago, y puede ver sus cuentas, movimientos y estados de cuenta en su billetera Venti (pay.ventipay.com/wallet).

Siguiente paso

Sigue con Estados de cuenta y cobranza para entender cómo y cuándo llega el dinero a tu balance.