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: los cobros se hacen con tarjetas de prueba.

Sandbox es un entorno aparte

Sandbox es un entorno completamente separado de producción, con su propio dashboard, sus propios usuarios y sus propios datos. Nada de lo que hagas en sandbox aparece en producción, ni al revés.

Tienes que registrarte por separado en dashboard.sandbox.vexorpay.com (se ingresa con un código que llega por email): tu cuenta de producción no existe en sandbox. El dashboard de sandbox se identifica con el banner naranja Modo sandbox. Ahí activas una cuenta de cobro de prueba y ves todo lo que creas en modo de prueba: los links de pago, las ventas, las suscripciones 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 en el dashboard de sandbox, y 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: cuenta de cobro de prueba

Para crear links con una clave de prueba (vxp_test_...) tienes que activar la cuenta de cobro de prueba desde el dashboard de sandbox (dashboard.sandbox.vexorpay.com). La verificación de identidad de sandbox no hace controles reales. Sin la cuenta de cobro, la API devuelve:

{
  "error": "payment_account_not_ready",
  "message": "Activate your payment account from the dashboard before creating payment links."
}

Los checkouts de prueba usan tarjetas de prueba:

Con cualquier fecha futura y cualquier CVC. Nadie paga dinero real: todo queda dentro del entorno sandbox. En sandbox no hay retiros (el saldo de prueba no se puede retirar), solo se puede pagar con tarjeta y no se pueden provocar disputas.

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.
• Los ids de sandbox y de producción no se cruzan: un link, una venta o un webhook de sandbox no existe en producción.
• 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.