Modo sandbox

El modo sandbox es el entorno de prueba de vexorpay. Te permite desarrollar y validar tu integración completa (crear links, generar checkouts, recibir webhooks y consultar ventas) sin mover dinero real: opera con el entorno de prueba de Polar y tarjetas de prueba.

Sandbox tiene su propio dashboard

El modo sandbox vive en su propio dashboard, separado del de producción:

El dashboard de sandbox se identifica con el banner naranja Modo sandbox. Ahí conectas tu cuenta de Polar de prueba y ves reflejado todo lo que creas en modo de prueba: los links de pago, las ventas, los movimientos y el saldo de prueba.

El modo lo define la API key, no el request. Todo lo que creas con una clave de prueba (vxp_test_...) se ve reflejado en el dashboard de sandbox. Links y ventas de prueba aparecen únicamente ahí, aislados de tus datos de producción. Al revés también funciona: lo que creas desde el dashboard de sandbox queda disponible para tu integración en modo de prueba.

Cómo se activa

El modo sandbox se elige con la API key, no request a request. Puedes tener dos familias de claves, creadas desde el dashboard correspondiente:

La clave lleva el modo en su propio formato:

• Producción: vxp_live_<shard>_<entropy>
• Pruebas/sandbox: vxp_test_<shard>_<entropy>

<shard> son 10 caracteres hex que identifican al usuario. La clave se muestra una sola vez al crearla: si la pierdes, revócala y crea una nueva. Cada modo tiene su propio límite de 20 claves.

El parámetro sandbox ya no existe en ninguna request: ni en el body de los POST ni en el query string de los GET. El modo sale de la clave. Las respuestas igual llevan el campo "sandbox": true o "sandbox": false en cada recurso: es informativo, no modifica nada.

Hosts y modo

Cada host de API acepta solo claves de su modo:

Si la clave no coincide con el host, la API responde 403 con:

{
  "error": "livemode_mismatch",
  "message": "La clave del request y el host no coinciden en modo (prueba/producción)."
}

# Correcto: clave de prueba contra el host de sandbox
curl https://api.sandbox.vexorpay.com/api/v1/payment-links \
  -X POST \
  -H "Authorization: Bearer vxp_test_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 19,
    "title": "Ebook UX (test)",
    "reference": "TEST-CATALOGO"
  }'

Los tokens OAuth (vxo_at_...) no pasan por el gate de host: el modo queda fijado por la conexión.

Compatibilidad

Las claves creadas con los formatos anteriores (vxp_u_<shard>_... y el viejo vxp_live_...) siguen funcionando y son de producción.

Requisito previo: Polar de prueba conectado

Para crear links con una clave de prueba (vxp_test_...) tienes que conectar Polar de prueba (sandbox de Polar) desde el dashboard de sandbox (dashboard.sandbox.vexorpay.com). Sin esa conexión, la API devuelve:

{
  "error": "account_not_connected",
  "message": "Connect Polar from the dashboard before creating payment links."
}

Los checkouts de prueba usan tarjetas de prueba (p. ej. 4242 4242 4242 4242). Nadie paga dinero real: todo queda dentro del entorno sandbox.

Consultar los recursos de prueba

No hay filtros de entorno para leer datos: con una clave de prueba (vxp_test_...) contra api.sandbox.vexorpay.com, los mismos endpoints devuelven directamente los recursos de prueba — links, ventas, clientes, disputas, suscripciones, saldo, retiros y eventos.

curl "https://api.sandbox.vexorpay.com/api/v1/payment-links" \
  -H "Authorization: Bearer vxp_test_tu_clave"

Los entornos no se mezclan: un checkout con clave de prueba solo funciona contra un link de prueba, y viceversa. El campo "sandbox" de cada respuesta sigue existiendo (true o false), pero ya no se usa para elegir el entorno.

Buenas prácticas

• Usa tus claves de prueba solo para desarrollo: los datos de sandbox no generan cobros ni retiros reales.
• No mezcles claves: una clave live se usa solo contra api.vexorpay.com y una de prueba solo contra api.sandbox.vexorpay.com.
• Cuando tu integración esté lista, crea los mismos recursos con tu clave live (vxp_live_...) para pasar a producción.