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)Delivered by Migo, then link + activateMigo physical prepaid card, fundable inside the wallet
Linked / third-partyPOST /users/{userId}/linked-cardsExternal card the cardholder already owns

POST /users/{userId}/cards (with a required clientId query parameter) links an existing physical card to a user; it is then activated β€” see Card lifecycle. Physical cards are delivered by Migo; there is no virtual card issuance.

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.