Sandbox (modo de prueba)

El sandbox es una copia vacía y aislada de tu organización donde puedes probar tu integración de principio a fin: crear productos, planes y clientes, abrir un checkout, cobrar y recibir webhooks, sin mover dinero real y sin tocar ningún banco.

Detrás del checkout del sandbox no hay un banco: hay un banco simulado que responde lo que tú le pidas. Todo lo demás —las páginas de checkout, el motor de cobros, los estados de la suscripción y la factura, los webhooks, el panel— es exactamente el mismo código que corre en producción.

Esta función se está habilitando organización por organización. Mientras tu organización no la tenga activa, tu clave de prueba (pvtk_) sigue comportándose como hasta ahora: se acepta igual que la clave de producción y actúa sobre tus datos reales. Si no estás seguro, revisa el campo livemode de cualquier respuesta.

Qué puedes hacer

Quiero…	Dónde
Cobrar una suscripción de prueba de punta a punta	Primeros pasos
Ensayar un rechazo, una demora o una domiciliación sin aprobar	Valores de prueba
Cobrar un pago único por débito inmediato o con tarjeta, y ver cada desenlace	Valores de prueba
Destrabar una domiciliación con el checkout ya en curso	Test helper
Ver los datos del sandbox en el panel y copiar mi catálogo	El sandbox en el panel
Recibir y verificar webhooks de prueba	Probar webhooks
Saber si ya estoy listo para cobrar de verdad	Salir a producción

Cambiar de mundo: la clave decide

No hay un parámetro de "modo", ni una URL distinta, ni otro Organization. Lo único que cambia es cuál de tus dos claves presentas:

Clave	Prefijo	Sobre qué actúa	`livemode`
Clave privada	`pvk_`	Tu organización real. Dinero real.	`true`
Clave de prueba	`pvtk_`	Tu organización sandbox. Banco simulado.	`false`

Las dos viven en el panel, en Desarrolladores → API Keys.

El header Organization no cambia: sigue llevando el id de tu organización real en los dos casos. Es la clave la que selecciona el mundo.

Producción

curl -X GET "https://api.venflow.app/v1/products" \
  -H "Api-Key: pvk_3f8a2c9d1b0e4a7f6c5d8e9a0b1c2d3e4f5a6b7c8d9e0f1a" \
  -H "Organization: org_xyz789..."

Sandbox — misma URL, mismo Organization, otra clave

curl -X GET "https://api.venflow.app/v1/products" \
  -H "Api-Key: pvtk_9b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a" \
  -H "Organization: org_xyz789..."

Esa segunda llamada devuelve una lista vacía: los productos de tu organización real no existen en el sandbox, y nada de lo que crees en el sandbox aparecerá en producción. El aislamiento es total y va en las dos direcciones.

El id de tu organización sandbox no se puede usar directamente. Si lo mandas en el header Organization, la autenticación falla con el mismo error que una clave inválida. La única puerta al sandbox es tu clave pvtk_.

Se crea solo

No tienes que pedir nada ni crear nada: la primera vez que usas tu clave de prueba —o la primera vez que enciendes el modo sandbox en el panel— Venflow crea tu organización sandbox y la deja lista para cobrar contra el banco simulado.

Es idempotente: siempre es la misma organización sandbox, por más veces que la uses.
Cada organización tiene exactamente uno, y un sandbox no puede tener un sandbox propio.
Si tu organización real está deshabilitada, la clave de prueba tampoco funciona: el sandbox no es una puerta trasera.

Lo que sí tienes que hacer es poblarlo. El sandbox nace vacío: sin productos, sin planes, sin clientes. Puedes crearlos con tu clave pvtk_ (ver Primeros pasos) o copiar tu catálogo real desde el panel.

Los medios de pago del sandbox

El sandbox ofrece siempre los mismos medios de pago, sin importar con qué banco cobra tu organización real (R4, Sypago o BNC). Así puedes ensayar un cobro con tarjeta aunque tu banco de producción todavía no te lo ofrezca, o un débito inmediato aunque hoy solo cobres por domiciliación.

Medio	Para qué cobros	Lo decide
Domiciliación	Planes recurrentes: la validación inicial y cada renovación	La cédula del pagador
Débito inmediato	Pagos únicos y links de pago	La cédula del pagador y un código OTP reservado
Tarjeta	Pagos únicos y links de pago	El número de la tarjeta

Dos reglas que conviene saber:

Lo que tienes habilitado en tu organización real, lo tienes en el sandbox. El pago con tarjeta, Cobro por API y el resto de las funciones que se van activando organización por organización se evalúan para tu organización real, y el sandbox hereda la respuesta. Si en producción no ves la pestaña de tarjeta, en el sandbox tampoco.
Pago Móvil no está en el sandbox. Es un medio que se verifica contra el banco y no hay banco contra el cual verificar. En producción está disponible para los comercios que cobran por BNC. Detalles en Lo que no se puede ensayar.

Los valores que eligen cada desenlace están en Valores de prueba.

`livemode`: cómo saber en qué mundo estás

Todo recurso que devuelve la API trae el campo livemode:

livemode: true — objeto real, creado con tu clave pvk_.
livemode: false — objeto del sandbox, creado con tu clave pvtk_.

Vale para clientes, productos, planes, descuentos, pagos, facturas, links de pago, medidores de uso, suscripciones y sesiones de checkout. Las listas lo traen en cada elemento de data, no en la envoltura; las respuestas de borrado, que solo confirman el id, tampoco lo llevan.

Los webhooks también lo traen en el payload, para que tu handler distinga un ensayo de un cobro de verdad sin mirar nada más. Ver Probar webhooks.

Usa livemode como interruptor en tu código: si tu handler escribe en tu contabilidad, haz que ignore (o marque aparte) todo lo que llegue con livemode: false.

Qué NO hace el sandbox

Límite	Detalle
No manda correos ni SMS a nadie	La organización sandbox no tiene configuración de notificaciones ni una dirección de correo que exista, así que no sale nada hacia afuera. El código OTP del débito inmediato tampoco se envía: cualquier código de ocho dígitos sirve.
No avisa al equipo de Venflow	Un cobro que queda en revisión manual en producción alerta a una persona. En el sandbox queda registrado igual, pero no alerta a nadie: es tu ensayo.
No copia clientes ni cobros	La copia de catálogo trae productos, planes, medidores y descuentos. Los clientes, las suscripciones y las facturas los genera tu prueba.
No promueve datos	Nada creado en el sandbox se puede mover a producción, ni al revés.
Pago Móvil no está disponible	Se verifica contra el banco, y en el sandbox no hay banco. Domiciliación, débito inmediato y tarjeta sí funcionan, siempre, con cualquier banco de producción.
Un solo sandbox por organización	No se puede borrar y volver a crear vacío desde el panel.

Preguntas frecuentes

¿Mi clave de prueba puede tocar datos reales? Con la función activa, no: pvtk_ solo alcanza tu organización sandbox. Mientras no esté activa para tu organización, sí — es el comportamiento anterior, y es exactamente por eso que existe esta función.

¿Tengo que cambiar la URL de la API? No. Es la misma https://api.venflow.app en los dos mundos.

¿Los cobros recurrentes también corren en el sandbox? Sí. Una suscripción creada en el sandbox se renueva como cualquier otra, contra el banco simulado, y el pagador conserva el desenlace que eligió su cédula.

¿Por qué no veo la pestaña de tarjeta en mi sandbox? Porque tu organización real no tiene el pago con tarjeta habilitado. El sandbox ofrece exactamente lo que tienes habilitado en producción; cuando se active para tu organización, aparece en los dos mundos a la vez.

¿Puedo tener varias pruebas corriendo a la vez? Sí. Los valores de prueba y el test helper trabajan por pagador, no por organización, así que varios checkouts vivos en el mismo sandbox no se pisan entre ellos.

Sandbox (modo de prueba)

En esta página