Cobro por API en el sandbox

Cobro por API en el sandbox

Si tu organización usa Cobros por API, todo el flujo funciona también en el sandbox: creas el link, el cliente afilia su cuenta, tu sistema pide el cobro y recibes el resultado por webhook. La diferencia es que el banco es simulado, así que ningún cobro mueve dinero real y tú decides qué responde el banco.

Es la forma de comprobar que tu integración maneja bien cada desenlace —un débito aprobado, un rechazo, un reintento que termina fallando— antes de cobrarle a un cliente real.

El flujo, con tu llave de prueba

1. Crea el link en modo "Cobro por API", con el dashboard en Modo sandbox o por API con tu llave pvtk_ y "collection_mode": "external" en POST /v1/checkout/sessions o POST /v1/payment-links. Crear el link es parte de lo que conviene ensayar, por eso no se copia desde tu organización real.
2. Completa el checkout con una cédula de los valores de prueba. La cédula del cliente decide qué responderá el banco en cada cobro de esa suscripción.
3. Pide el cobro con tu llave pvtk_:

curl -X POST "https://api.venflow.app/v1/subscriptions/<subscription_id>/charges" \
  -H "Api-Key: pvtk_9b1c..." \
  -H "Organization: org_xyz789..." \
  -H "Idempotency-Key: 5b7c2d10-1a2b-4c3d-9e8f-0a1b2c3d4e5f" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10, "retry_policy": "automatic" }'

4. Recibe el webhook con el resultado, igual que en producción.

El Organization es siempre el de tu organización real: lo que te lleva al sandbox es la llave pvtk_.

livemode: false

Todo lo que produce el sandbox lo dice:

• Cada cobro que devuelve el API (crear, listar, consultar, cancelar) trae "livemode": false.
• Cada webhook de cobro (EXTERNAL_CHARGE_SUCCESS_EVENT, EXTERNAL_CHARGE_FAILED_EVENT, EXTERNAL_CHARGE_CANCELLED_EVENT) trae "livemode": false.

Con tu llave de producción, los mismos objetos traen "livemode": true. Si tu servidor recibe webhooks de los dos mundos en el mismo endpoint, usa ese campo para que un ensayo nunca termine en tu contabilidad real.

Qué responde el banco en cada cobro

La cédula del cliente decide el desenlace, con el mismo significado que en el checkout.

Hay una diferencia importante en el checkout de un link "Cobro por API" sin cobro inicial: ahí las cédulas de rechazo (00000002 y 00000003) no rechazan la afiliación. El cliente afilia su cuenta y el rechazo llega en los cobros que pidas después, que es lo que necesitas ensayar. Las cédulas de espera (00000004, 00000005 y 00000007) se comportan igual que en cualquier checkout.

Los montos no cambian el desenlace: puedes cobrar lo que quieras.

Ejecutar un cobro ahora

Un cobro con charge_date futura se ejecuta ese día, y el motor revisa los cobros solo cuatro veces al día. Para no esperar, el sandbox tiene un helper que ejecuta un cobro de inmediato:

curl -X POST "https://api.venflow.app/v1/test_helpers/charges/<charge_id>/execute" \
  -H "Api-Key: pvtk_9b1c..." \
  -H "Organization: org_xyz789..."

La respuesta es el cobro tal como quedó al despacharlo, normalmente processing. El resultado llega después por webhook, como siempre.

• Un cobro scheduled se ejecuta ya, sin importar su charge_date.
• Un cobro automatic que espera su próximo reintento ejecuta ese reintento ya. Cada llamada ejecuta como máximo un intento.
• No mueve el reloj de tu organización ni toca ningún otro cobro.

Recorrer los reintentos hasta el final

Con un cliente de cédula 00000003 y retry_policy: automatic:

1. Crea el cobro y ejecútalo con el helper: el banco lo rechaza y queda processing.
2. Llama al helper otra vez: se ejecuta el siguiente reintento, que también se rechaza.
3. Repite. Cuando se agotan los reintentos de tu sandbox, la solicitud pasa a failed y llega un único EXTERNAL_CHARGE_FAILED_EVENT con "livemode": false.

En el sandbox los reintentos también corren solos, cada 5 minutos y hasta 5 por día. El helper sirve para no esperar: ni los 5 minutos entre intentos ni el día siguiente cuando llegas a ese límite.

Si solo quieres ver el webhook de fallo, usa 00000002: falla de una vez.

Cuándo responde con error

Ninguno de esos casos cambia nada. Llamar al helper dos veces a la vez sobre el mismo cobro tampoco cobra dos veces: solo una de las llamadas ejecuta el intento.

Referencia del endpoint: Ejecutar un cobro ahora.

Lo que se comporta igual que en producción

• La idempotencia: la misma Idempotency-Key devuelve el mismo cobro.
• La cancelación: solo un cobro scheduled se puede cancelar.
• La protección contra el doble cobro: si hay un cobro en camino al banco, el siguiente se pospone.
• Si apagan la función después de programar un cobro, ese cobro igual se ejecuta en su fecha. Los cobros nuevos, en cambio, se rechazan con 404.

En la lista para salir a producción

Si tu organización usa Cobro por API, la lista para salir a producción muestra un paso más: "Cobro por API probado en el sandbox". Se marca solo cuando un cobro de tu sandbox termina en completed, y muestra cuándo. Como el resto de la lista, es una guía: no bloquea nada.