> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vitawallet.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox y pruebas

> Cómo probar tu integración end-to-end sin mover dinero real.

Sandbox (también llamado *Staging*) es un ambiente aislado para construir y certificar tu integración. Las wallets, usuarios, transacciones y webhooks son completamente independientes de producción.

> [!WARNING]
>
> Los identificadores (IDs de bancos, métodos de pago, currencies, networks) **no son los mismos** entre Sandbox y Producción. Nunca hagas hard-code — consulta los endpoints de metadatos (`/withdrawal_rules`, `/payment_methods/{country}`, `/networks`, `/prices`) en runtime.

## Checklist antes de empezar

**1. Cuenta Sandbox verificada**

Registra tu cuenta business en [stage.vitawallet.io](https://stage.vitawallet.io) y completa el flujo de verificación. En Sandbox los datos no necesitan ser reales, pero sí deben estar completos.

**2. Credenciales de API emitidas**

Pídelas desde la sección **Integraciones** de la plataforma. Guarda `x-login`, `x-trans-key` y `secret` en tu secret manager — nunca en el código.

**3. Webhook URL pública alcanzable**

Para probar notificaciones end-to-end necesitas una URL HTTPS pública. Para desarrollo local usa un túnel (ngrok, Cloudflare Tunnel, o similar). Configúrala con `PUT /api/businesses/webhooks`.

**4. Fondos de prueba en wallets**

Para probar payouts/exchanges necesitas saldo en Sandbox. Solicita el acreditado inicial a tu contacto de integración de Vita.

## Datos de prueba

> [!NOTE]
>
> Los valores exactos de pruebas (números de tarjeta, cuentas bancarias, IBAN/CBU/CLABE, direcciones blockchain, montos que fuerzan estados `paid`/`denied`/`expired`) **no se publican por seguridad**. Solicítalos a [empresas@vitawallet.io](mailto:empresas@vitawallet.io) o a tu contacto de integración — recibirás un documento con los valores vigentes para Sandbox.

Lo que sí puedes documentar del lado tuyo:

* **Países y monedas activas en tu cuenta Sandbox.** Varían según tu configuración.
* **Métodos de payin disponibles por país.** Consulta `GET /api/businesses/payment_methods/{country_iso_code}`.
* **Reglas de payout por destino.** `GET /api/businesses/withdrawal_rules`.
* **Networks crypto habilitadas.** `GET /api/businesses/networks`.

## Flujos recomendados para certificar

Antes de pedir credenciales de producción, prueba **al menos 10 operaciones por endpoint** que vayas a usar. Como mínimo, cubre estos escenarios:

> [accordion] Payin — happy path
>
> Crear `Payment Order` → cliente paga → recibir webhook `payment_order.paid` → verificar con `GET /payment_orders/:id`.

> [accordion] Payin — fallo del cliente
>
> Crear `Payment Order` → simular intento fallido → recibir webhook `payment_order_attempt.cancelled` → confirmar que el order **sigue vigente** y acepta un nuevo intento.

> [accordion] Payin — expiración
>
> Crear `Payment Order` → dejar expirar → recibir webhook `payment_order.expired`.

> [accordion] Payout bancario — happy path
>
> `GET /prices` → `GET /withdrawal_rules` para el país destino → crear `withdrawal` → recibir webhook `transaction.completed`.

> [accordion] Payout — denied
>
> Forzar denegación usando valores de prueba proporcionados por Vita → recibir `transaction.denied` → leer `statuses[]` para obtener la razón.

> [accordion] Exchange
>
> `GET /crypto_prices` → `POST /transactions` con `transactions_type: exchange` **dentro de la ventana `valid_until`** → verificar débito/crédito en wallets origen y destino.

> [accordion] Idempotencia
>
> Simular timeout en un `POST /transactions` → re-consultar con `GET /transactions?order=<tu-order>` → confirmar que no haya duplicado antes de reintentar. Ver [Idempotencia y reintentos](https://docs.vitawallet.io/idempotency-retries.md).

> [accordion] Webhook signature
>
> Enviarte un evento desde Sandbox → validar la firma HMAC-SHA256 en tu servidor → responder `200`. Rechazar firmas inválidas.

## Debugging de webhooks

* `GET /api/businesses/events` devuelve los **últimos eventos emitidos por Vita**, con el status HTTP que tu endpoint respondió. Úsalo para diagnosticar por qué un webhook no llegó o fue reintentado.
* Si tu endpoint devolvió no-200, Vita reintenta con backoff. Mientras depuras, puedes forzar reintentos desde tu lado respondiendo 200 recién cuando tu procesador esté listo.

## De Sandbox a Producción

Antes del cutover:

> [!TIP]
>
> Tu backend valida la firma HMAC de cada webhook y rechaza las inválidas.

> [!TIP]
>
> Guardaste `order` únicos por operación y haces idempotency check antes de reintentar.

> [!TIP]
>
> No hay IDs hardcodeados (bancos, currencies, networks).

> [!TIP]
>
> Manejas los estados finales (`paid`, `expired`, `cancelled`, `completed`, `denied`, `failed`) explícitamente.

> [!TIP]
>
> Agendaste la reunión de certificación con el equipo técnico de Vita.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.