> ## 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. # Preguntas frecuentes > Dudas recurrentes de integradores: credenciales, firma, webhooks, idempotencia y reconciliación. > [accordion] ¿Cómo obtengo mis credenciales de API? > > 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. > [accordion] ¿Puedo usar las mismas credenciales en Sandbox y Producción? > > 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. > [accordion] Recibo `422 Invalid signature`. ¿Qué reviso? > > 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. > [accordion] ¿Cuál es la diferencia entre `x-login`, `x-trans-key` y `secret`? > > * `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](mailto:empresas@vitawallet.io). > [accordion] ¿Qué pasa si un POST a /transactions responde timeout? > > La transacción **puede o no haberse creado** del lado de Vita. No reintentes aún. Primero consulta `GET /api/businesses/transactions?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](https://docs.vitawallet.io/idempotency-retries.md). > [accordion] Un `payment_order_attempt.cancelled` ¿cancela el Payment Order? > > 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). > [accordion] ¿Por qué no recibo webhooks de `payment_order.*`? > > 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. > [accordion] ¿Puedo recibir webhooks en una IP privada o localhost? > > 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. > [accordion] ¿Cuánto tiempo tengo para responder un webhook? > > 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. > [accordion] ¿Cómo deduplico eventos de webhook? > > 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. > [accordion] ¿Se puede cancelar un Payment Order desde la API? > > 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. > [accordion] ¿Cómo calculo cuánto va a recibir el beneficiario de un payout bancario? > > 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. > [accordion] ¿Puedo hacer exchange fiat → fiat? > > 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. > [accordion] ¿Qué incluyo en la firma del body del payout? > > **Todos los campos** del body, incluyendo `transactions_type`. Un error común es excluir `transactions_type` del body ordenado — causa `Invalid signature`. > [accordion] ¿Cómo reconcilio diariamente? > > 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. > [accordion] ¿Dónde reporto bugs o pido features? > > Para integradores existentes: contacta a tu ejecutivo técnico de Vita o escribe a [empresas@vitawallet.io](mailto:empresas@vitawallet.io) con: > > * Ambiente (Sandbox / Producción) > * Timestamp y `x-login` > * Request body / response completos (sin credenciales) > * Comportamiento esperado vs observado This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.