Skip to main content
Desde la plataforma web de Vita Wallet, en la sección Integraciones. Hay un botón para enviar las credenciales al email registrado. Primero obtienes credenciales de Sandbox; las de Producción se emiten solo después de certificar la integración con el equipo técnico de Vita.
No. Son credenciales separadas y las bases de datos están aisladas. Un ID (bancos, currencies, networks) que funciona en Sandbox no funciona en Producción.
En orden:
  1. Reloj del servidor sincronizado (NTP). El x-date debe estar dentro de ±1 minuto del reloj de Vita.
  2. Formula correcta. La API general ordena las claves del body alfabéticamente y concatena sin separadores. El módulo Users y la verificación de Webhooks entrantes usan JSON.stringify(body) tal cual — no sort.
  3. Credenciales del ambiente correcto. Sandbox vs Producción no se cruzan.
  4. Body no modificado después de calcular la firma.
  • x-login: identificador de tu business (40 caracteres hex). Se envía en el header de cada request.
  • x-trans-key: segundo identificador (ligado a la operación API). Se envía en el header.
  • secret: clave privada usada como key del HMAC. Nunca se envía al servidor, solo se usa para firmar.
Si cualquier credencial se expone, pide rotación inmediata a empresas@vitawallet.io.
La transacción puede o no haberse creado del lado de Vita. No reintentes aún. Primero consulta GET /api/businesses/transactions?order=<tu-order>:
  • Si vuelve un resultado → la transacción se creó; usa ese ID.
  • Si no vuelve nada → puedes reintentar el POST con el mismo order.
Patrón completo en Idempotencia y reintentos.
No. Solo cancela ese intento específico. El Payment Order sigue vigente y el usuario puede abrir un nuevo intento que lo mueva a paid. Un Payment Order solo pasa a estado terminal con payment_order.paid, payment_order.expired, o payment_order.cancelled (este último lo dispara Vita internamente, no el cliente).
Las notificaciones payment_order.* y payment_order_attempt.* solo se envían si tu configuración incluye la categoría payment. Estar suscrito a deposit u otras categorías no entrega estos eventos. Verifica con GET /api/businesses/webhooks y actualiza con PUT /api/businesses/webhooks incluyendo payment en la lista.
No. La URL debe ser HTTPS pública y alcanzable desde Internet. Para desarrollo local, usa un túnel (ngrok, Cloudflare Tunnel). En producción, debe ser un endpoint estable en tu infraestructura.
Menos de 5 segundos con 200 OK. Procesa la lógica pesada de forma asíncrona (encola el evento y responde 200). Si tardas más, Vita puede cerrar la conexión y reintentar — lo que te obliga a deduplicar.
Usa event_id como clave de deduplicación. Trátalo como un string opaco — no asumas formato UUID aunque lo parezca; algunos eventos añaden sufijos numéricos.
No. No existe operación de cancelación expuesta. Un Payment Order llega a estado terminal por:
  • Pago exitoso (paid)
  • Expiración (expired)
  • Cancelación interna de Vita por motivos operativos o compliance (cancelled)
Diseña tu integración para manejar los tres casos.
  1. Consulta GET /api/businesses/prices — obtienes la tasa de cambio y el costo fijo por destino.
  2. Calcula: monto_destino = (monto_origen × tasa) − costo_fijo_destino.
  3. Confirma con GET /api/businesses/withdrawal_rules para el país destino: puede haber mínimos/máximos adicionales.
El valid_until del endpoint de prices limita cuánto tiempo esa tasa es válida para crear el payout.
No. El servicio de Exchange solo permite cripto → fiat, fiat → cripto, o cripto → cripto. Fiat a fiat se maneja con un Bank Payout en moneda destino.
Todos los campos del body, incluyendo transactions_type. Un error común es excluir transactions_type del body ordenado — causa Invalid signature.
Agenda un job que:
  1. Llame a GET /api/businesses/transactions/get_all_transactions con un rango de fecha (YYYY-MM-DD).
  2. Pagine todos los resultados.
  3. Cruce contra tu base de datos por order (tu identificador).
  4. Marque discrepancias para revisión manual.
No uses webhooks como única fuente — captura casos donde el webhook no llegó por caídas transitorias.
Para integradores existentes: contacta a tu ejecutivo técnico de Vita o escribe a empresas@vitawallet.io con:
  • Ambiente (Sandbox / Producción)
  • Timestamp y x-login
  • Request body / response completos (sin credenciales)
  • Comportamiento esperado vs observado