Wallet
La API de Inyo Wallet es un libro contable de partida doble para custodiar y mover dinero entre billeteras con nombre. Impulsa casos de uso B2B como dividir transferencias bancarias entrantes entre sub-billeteras de proveedores, retenciones de preautorización estilo tarjeta con captura parcial y trazabilidad de fondos con calidad de auditorÃa.
Conceptos Clave
Billeteras
Una billetera es una cuenta con nombre que te pertenece. Cada billetera mantiene saldos en uno o más activos (USD, USDC, EUR, MXN). Los saldos se calculan a partir del libro contable — nunca se escriben directamente.
Cada billetera es propiedad de una company o un user, identificado por un owner_ref que tú proporcionas (tu propio ID para esa entidad).
Libro Contable de Partida Doble
Cada operación escribe un journal (asiento) con dos o más entries (movimientos). Cada movimiento es un débito o un crédito, y la suma de los débitos es igual a la suma de los créditos, por activo, en cada journal. Esto hace imposible que el dinero aparezca o desaparezca — un bug solo puede, a lo sumo, desviarlo.
No escribes movimientos directamente. Llamas a los endpoints de operaciones (depósito, retención, captura, anulación, reembolso, transferencia, conversión FX) y el libro contable escribe los movimientos correctos de forma atómica.
Saldos: posted, held, available
Cada saldo de billetera tiene tres números por activo:
| Campo | Significado |
|---|---|
posted | Suma acumulada con signo de todos los movimientos — lo que la billetera realmente ha recibido menos lo que ha enviado |
held | Suma de las preautorizaciones abiertas — dinero reservado pero aún no gastado |
available | posted − held — saldo disponible para gastar |
Cuando preautorizas, held sube (y posted baja — la preautorización mueve los fondos a una subcuenta de retención). Cuando capturas, los fondos se mueven de la retención al destino. Cuando anulas, held vuelve a bajar y los fondos regresan.
OrÃgenes y Linaje
Cada dólar en el sistema se remonta a un origen (source) — una transferencia bancaria, un débito ACH, un cobro con tarjeta o un depósito de stablecoin. Cuando divides una transferencia de $10k entre 10 billeteras, cada movimiento de crédito lleva un lineageRef que apunta al origen.
Más adelante, cuando una billetera gasta dinero, los movimientos de débito también llevan lineageRef — apuntando al origen u orÃgenes de donde provino originalmente el dinero. El libro contable usa consumo FIFO: el dinero entrante más antiguo se gasta primero.
Esto te da respuestas con calidad de auditorÃa a "¿de dónde vino este dólar especÃfico?" — requerido para AML, lotes fiscales en stablecoins y atribución de contracargos.
Solo Inserción
Los journals y los movimientos nunca se actualizan ni se eliminan — la inmutabilidad se aplica a nivel de base de datos. Una "reversión" es un journal compensatorio que referencia al original mediante parentJournalId, de modo que las cadenas de operaciones permanecen trazables: reembolso → captura → preautorización.
Autenticación y Convenciones
- Cada endpoint vive bajo
/organizations/{tenant}/en el host de la API de wallet (https://{FQDN}), autenticado con tu API key de tenant en el headerX-API-KEY. - Cada POST requiere un header
Idempotency-Key— ver Idempotencia. - Todos los montos son strings en JSON, decimales con hasta 8 posiciones. Nunca parsees los montos como números de punto flotante — perderás precisión.
- Los campos
idde billeteras, retenciones y journals son UUIDs. Campos comoaccountIdyjournalIddentro de los movimientos son identificadores numéricos internos — usa los UUIDs para las llamadas a la API.
Por Dónde Empezar
- GuÃa de Integración — un escenario B2B real de principio a fin: depósito de transferencia bancaria dividido entre billeteras de proveedores, preautorización, captura parcial, reembolso y anulación
- Referencia de la API — todos los endpoints, códigos de error y semántica de idempotencia