# Modo sandbox

Prueba tu integración con Polar de prueba, sin mover dinero real. El modo lo define la API key: las de producción llevan vxp_live_ y las de prueba vxp_test_.

> [!WARNING]
> El SDK `vexor` de npm (Stripe, MercadoPago, PayPal, Square, Talo) está **deprecado**: ya no se mantiene y no debe usarse. vexorpay es hoy una **API REST de links de pago en USD sobre Polar (Merchant of Record), sin SDK oficial**. Migración: <https://developers.vexorpay.com/docs/migracion-desde-el-sdk>

Fuente: <https://developers.whop.vexorpay.com/docs/sandbox-mode>

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:

| Entorno | Dashboard |
| --- | --- |
| Producción | `https://dashboard.vexorpay.com` |
| **Sandbox (pruebas)** | `https://dashboard.sandbox.vexorpay.com` |

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:

| Dashboard | Claves que creas |
| --- | --- |
| `dashboard.vexorpay.com` (producción) | Claves **live** (`vxp_live_...`) |
| `dashboard.sandbox.vexorpay.com` (pruebas) | Claves de **prueba** (`vxp_test_...`) |

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:

| Host | Claves que acepta |
| --- | --- |
| `https://api.vexorpay.com` (producción) | Solo `vxp_live_...` |
| `https://api.sandbox.vexorpay.com` (sandbox) | Solo `vxp_test_...` |

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

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

```bash
# 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:

```json
{
  "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.

```bash
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.