Primeros pasos

Esta guía va de un sandbox vacío a una suscripción activa con su primera factura pagada, sin tocar ningún banco. Son cinco llamadas y un formulario.

Necesitas tu clave de prueba (pvtk_), que está en el panel en Desarrolladores → API Keys, y el id de tu organización real — el mismo que usas en producción.

Si prefieres no crear el catálogo a mano, puedes copiar el que ya tienes en producción desde el panel y saltar directo al paso 3.

1. Crea un producto

curl -X POST "https://api.venflow.app/v1/products" \
  -H "Api-Key: pvtk_9b1c..." \
  -H "Organization: org_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Plan de prueba"}'

Respuesta

{
  "object": "product",
  "id": "a02b29e4-54a3-452f-9c50-7bfaa8274a90",
  "name": "Plan de prueba",
  "active": true,
  "livemode": false
}

Fíjate en livemode: false: ese objeto vive en tu sandbox y no existe en producción.

2. Crea un plan sobre ese producto

curl -X POST "https://api.venflow.app/v1/plans" \
  -H "Api-Key: pvtk_9b1c..." \
  -H "Organization: org_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mensual de prueba",
    "type": "recurring",
    "frequency": "monthly",
    "price": 10.00,
    "product_id": "a02b29e4-54a3-452f-9c50-7bfaa8274a90"
  }'

Guarda el id que devuelve: es el plan que vas a cobrar.

Para un plan medido (usage_type: "metered") necesitas además un medidor (POST /v1/usage/meters) y un modelo de precio por uso. Se comporta igual en el sandbox que en producción.

3. Abre una sesión de checkout

curl -X POST "https://api.venflow.app/v1/checkout/sessions" \
  -H "Api-Key: pvtk_9b1c..." \
  -H "Organization: org_xyz789..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "PLAN_ID",
    "customer_data": {
      "name": "Ana",
      "last_name": "Prueba",
      "email": "ana.prueba@example.com",
      "doc_type": "V",
      "doc_id": "00000001",
      "phone": "04141234567"
    },
    "redirect_url": "https://tu-sitio.com/gracias"
  }'

Respuesta

{
  "object": "checkout.session",
  "id": "970425b4-1ea5-4aa7-a276-293f20adb4de",
  "status": "pending",
  "url": "https://checkout.venflow.app/clients?org=sbx_org_xyz789...&session=970425b4-...",
  "amount_total": 10,
  "livemode": false
}

El doc_id que mandaste, 00000001, es un valor de prueba: le dice al banco simulado que apruebe de inmediato. Cualquier otra cédula también aprueba; esta lo hace explícito.

4. Completa el checkout

Abre la url de la respuesta en el navegador. Es la misma página de checkout de producción, con una franja fija de "Modo de prueba" arriba que no se puede apagar.

El pagador recorre tres pantallas:

Datos de contacto y banco. Los campos que mandaste en customer_data vienen llenos. Elige un banco cualquiera de la lista: el banco que escoja el pagador se guarda como dato suyo, pero quien responde siempre es el banco simulado.
Autorización de domiciliación. Acepta las dos casillas y continúa. La pantalla te dirá que aprueban la solicitud en tu banca en línea; con 00000001 ya está aprobada, así que pulsa "Ya la aprobé".
Activar suscripción. Confirma y listo.

Al terminar, el navegador va a tu redirect_url.

5. Comprueba el resultado

curl -X GET "https://api.venflow.app/v1/subscriptions?limit=1" \
  -H "Api-Key: pvtk_9b1c..." \
  -H "Organization: org_xyz789..."

Deberías ver la suscripción en active, y su factura en paid:

curl -X GET "https://api.venflow.app/v1/invoices?limit=1" \
  -H "Api-Key: pvtk_9b1c..." \
  -H "Organization: org_xyz789..."

Los dos objetos traen livemode: false. No se movió dinero y ningún banco recibió nada.

Un pago único, por débito inmediato o con tarjeta

Un plan de tipo one_time ("type": "one_time", sin frequency) abre un checkout distinto: no domicilia nada, cobra una sola vez. El pagador elige cómo:

Débito inmediato. Escribe su cédula y su teléfono, pulsa Pagar y el checkout le pide un código OTP. En el sandbox no llega ningún SMS: cualquier código de ocho dígitos sirve, salvo 00000000, que siempre es "Clave incorrecta". Con el código aceptado, la cédula decide el desenlace como en la tabla de arriba.
Tarjeta. Aparece solo si tu organización real tiene el pago con tarjeta habilitado. 4111 1111 1111 1111 aprueba; 4000 0000 0000 0002 rechaza. Cualquier fecha futura y cualquier código de seguridad.

El pago queda como una factura paid sin suscripción, igual que un pago único real. Las tres tablas completas están en Valores de prueba.

Qué probar después

Que tu integración maneje los fallos, no solo el camino feliz: cambia el doc_id por otro valor de prueba y repite el paso 3.
Un pago único con cada desenlace: un débito inmediato rechazado, una tarjeta sin fondos, un cobro que queda en revisión.
Que tu servidor reciba los eventos: registra un webhook en el sandbox y dispara un evento de prueba.
Cuando ya todo funcione, revisa la lista para salir a producción.

Primeros pasos

En esta página