ARi LogoPortal de Desarrolladores
|
Volver a Documentacion

Wallet

Un Wallet es un saldo de custodia del lado ARi en una sola moneda, direccionable por wallet_id (UUID) e iban (formato costarricense, código de banco 0589). Los wallets son el origen, accesible para socios, de toda operación que mueve valor: createTransfer debita un wallet, createOrder resuelve los wallets de origen y destino por pierna, y getBalances devuelve fotografías de wallets.

Cada cliente tiene uno o más wallets. Una llave de suscripción ve únicamente los wallets que pertenecen a los clientes que administra.
Endpoints que lo devuelven GET /api/v1/balances (forma BalanceWalletDto), GET /api/v1/wallets (forma AriWalletDto)
Esquema en el cable AriWalletDto (canónico), BalanceWalletDto (con marca de tiempo de la fotografía)
Ciclo de vida Aprovisionado por ARi al dar de alta al cliente; nunca se elimina, solo se congela por operaciones.

Garantías del objeto

  • wallet_id es el identificador canónico para enrutar órdenes FX y seleccionar origen de transferencias. Prefiéralo sobre iban.
  • iban siempre lleva el código de banco 0589 (código bancario de ARi). Úselo para distinguir los wallets internos de ARi de las cuentas externas.
  • available_balance es lo que usted puede gastar ahora — descuenta reservas en vuelo y débitos no liquidados. No es el balance contable.
  • available_balance está denominado en currency — nunca asuma USD ni CRC; lea siempre el campo.
  • last_updated_at es el momento de refresco del ledger aguas arriba (solo en BalanceWalletDto). Por diseño puede atrasarse algunos segundos; para actualizaciones en tiempo real, suscríbase a los eventos SSE de wallet.
  • Un wallet por moneda por cliente — no existe partición de tipo "wallet USD 1" / "wallet USD 2".

Campos (`BalanceWalletDto` — devuelto por `GET /api/v1/balances`)

Campo Tipo Requerido Descripción
wallet_id string (uuid) sí Identificador principal. Ejemplo: "550e8400-e29b-41d4-a716-446655440000".
wallet_iban string (22 caracteres) sí IBAN costarricense. Ejemplo: "CR73058900000000054321".
available_balance number sí Saldo disponible en currency. Ejemplo: 250000.5.
currency string (ISO 4217) sí Moneda del wallet. Ejemplo: "CRC".
last_updated_at string (ISO 8601) sí Último refresco desde el ledger aguas arriba. Ejemplo: "2024-05-01T12:10:00.000Z".

Campos (`AriWalletDto` — devuelto por `GET /api/v1/wallets`)

Campo Tipo Requerido Descripción
wallet_id string (uuid) sí Identificador principal.
iban string (22 caracteres) sí IBAN costarricense, código de banco 0589.
currency string (ISO 4217) sí Moneda del wallet.
alias string no Nombre legible (solo UI).
available_balance number no Saldo disponible — se completa únicamente cuando el llamante tiene scope explícito de balance.

Ejemplo (`BalanceWalletDto`)

{
  "wallet_id": "550e8400-e29b-41d4-a716-446655440000",
  "wallet_iban": "CR73058900000000054321",
  "available_balance": 250000.5,
  "currency": "CRC",
  "last_updated_at": "2024-05-01T12:10:00.000Z"
}

Véase también