Skip to main content
Migo Docs

Wallet & Cards Overview

Entities​

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

Card types​

TypeHow obtainedUse case
Physical (Migo-issued)POST /users/{userId}/cards/virtualsMigo-issued card, fundable in-wallet
Linked / third-partyPOST /users/{userId}/linked-cardsExternal card the cardholder already owns

POST /users/{userId}/cards (with a required clientId query param) links an existing card to a user — see Card Lifecycle. The physical-card issuance endpoint is POST /users/{userId}/cards/virtuals.

Fund model​

Each card has:

  • Balance — available to spend (Decimal, up to 4 places, stored in the card's currency)
  • Pending debits — authorized but not yet captured
  • Pending credits — refunds not yet cleared

Balance changes only through:

  • POST /cards/{cardId}/funds — you add / withdraw funds as the issuer
  • Captured card payments — reduce balance
  • Refunds credited back — increase balance
  • Card-to-card transfers — move between two cards

Fund operations are atomic. You cannot overdraw; over-spend attempts return 7303 INSUFFICIENT_FUNDS.

Cardholder permissions​

Per-card, per-user permissions control who can do what. The real CardPermissionType values are:

  • checkCard — view card details
  • checkCvv — reveal the CVV
  • updateAlias — rename the card
  • updateStatus — block / unblock the card
  • assignPIN — set the card PIN
  • getCards — list cards
  • getAllTransfersByDate — read the movement feed
  • transferBetweenCards — move money to another card
  • activation — activate the card

A single card can have multiple authorized users (e.g. a couple sharing a card). Each user's permissions are granted independently.

Permissions management endpoints:

  • POST /cards/{cardId}/users/{authUserId}/permissions — grant permissions
  • PATCH /cards/users/permissions/{id} — update a permission record
  • GET /cards/users/{authUserId}/permissions — list a user's card permissions
  • GET /cards/{cardId}/users/permissions — list all permissions on a card
  • GET /cards/{cardId}/users/{authUserId}/permissions — list one user's permissions on one specific card

Cards summary​

The wallet app pulls an aggregated summary per cardholder over a date range:

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

startDate and endDate are required. This differs from GET /users/{userId}/cards, which lists the user's cards; the summary returns aggregate figures for the period.