Skip to main content
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.
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 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

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 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:
Crear Payment Order → cliente paga → recibir webhook payment_order.paid → verificar con GET /payment_orders/:id.
Crear Payment Order → simular intento fallido → recibir webhook payment_order_attempt.cancelled → confirmar que el order sigue vigente y acepta un nuevo intento.
Crear Payment Order → dejar expirar → recibir webhook payment_order.expired.
GET /prices → GET /withdrawal_rules para el país destino → crear withdrawal → recibir webhook transaction.completed.
Forzar denegación usando valores de prueba proporcionados por Vita → recibir transaction.denied → leer statuses[] para obtener la razón.
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.
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.
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:
Tu backend valida la firma HMAC de cada webhook y rechaza las inválidas.
Guardaste order únicos por operación y haces idempotency check antes de reintentar.
No hay IDs hardcodeados (bancos, currencies, networks).
Manejas los estados finales (paid, expired, cancelled, completed, denied, failed) explícitamente.
Agendaste la reunión de certificación con el equipo técnico de Vita.