Saltar al contenido principal
Migo Docs

Resumen de Wallet y Tarjetas

Entidades​

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Cardholder  │─1 N►│    Card     │─1 N►│  Movements  │
│             │     │             │     │             │
│ authUserId  │     │ cardId      │     │ transfers   │
│ profile     │     │ maskedPan   │     │ statements  │
│ permissions │     │ balance     │     │ refunds     │
└─────────────┘     └─────────────┘     └─────────────┘
       ▲
       │
       │ linked-cards (external cards)
       │
┌─────────────┐
│ Third-party │
│    card     │
└─────────────┘

Tipos de tarjeta​

TipoCómo se obtieneCaso de uso
Física (emitida por Migo)POST /users/{userId}/cards/virtualsTarjeta emitida por Migo, financiable dentro del wallet
Vinculada / de tercerosPOST /users/{userId}/linked-cardsTarjeta externa que el titular ya posee

POST /users/{userId}/cards (con un parámetro de consulta clientId requerido) vincula una tarjeta existente a un usuario — consulta Ciclo de vida de la tarjeta. El endpoint de emisión de tarjetas físicas es POST /users/{userId}/cards/virtuals.

Modelo de fondos​

Cada tarjeta tiene:

  • Saldo — disponible para gastar (Decimal, hasta 4 decimales, almacenado en la moneda de la tarjeta)
  • Débitos pendientes — autorizados pero aún no capturados
  • Créditos pendientes — reembolsos aún no liquidados

El saldo cambia únicamente a través de:

  • POST /cards/{cardId}/funds — agregas / retiras fondos como emisor
  • Pagos con tarjeta capturados — reducen el saldo
  • Reembolsos acreditados — aumentan el saldo
  • Transferencias tarjeta a tarjeta — mueven dinero entre dos tarjetas

Las operaciones de fondos son atómicas. No puedes sobregirar; los intentos de sobregasto devuelven 7303 INSUFFICIENT_FUNDS.

Permisos del titular​

Los permisos por tarjeta y por usuario controlan quién puede hacer qué. Los valores reales de CardPermissionType son:

  • checkCard — ver detalles de la tarjeta
  • checkCvv — revelar el CVV
  • updateAlias — renombrar la tarjeta
  • updateStatus — bloquear / desbloquear la tarjeta
  • assignPIN — establecer el PIN de la tarjeta
  • getCards — listar tarjetas
  • getAllTransfersByDate — leer el feed de movimientos
  • transferBetweenCards — mover dinero a otra tarjeta
  • activation — activar la tarjeta

Una sola tarjeta puede tener múltiples usuarios autorizados (por ejemplo, una pareja compartiendo una tarjeta). Los permisos de cada usuario se otorgan de forma independiente.

Endpoints de gestión de permisos:

  • POST /cards/{cardId}/users/{authUserId}/permissions — otorgar permisos
  • PATCH /cards/users/permissions/{id} — actualizar un registro de permiso
  • GET /cards/users/{authUserId}/permissions — listar los permisos de tarjeta de un usuario
  • GET /cards/{cardId}/users/permissions — listar todos los permisos de una tarjeta
  • GET /cards/{cardId}/users/{authUserId}/permissions — listar los permisos de un usuario sobre una tarjeta específica

Resumen de tarjetas​

La app del wallet obtiene un resumen agregado por titular sobre un rango de fechas:

GET /users/{userId}/cards/summary?startDate=2026-04-01&endDate=2026-04-30

startDate y endDate son requeridos. Esto difiere de GET /users/{userId}/cards, que lista las tarjetas del usuario; el resumen devuelve cifras agregadas del período.