Wallets

A wallet is the financial account object in the Money Service. Every user or module entity that participates in financial operations must have a wallet. One user can hold multiple wallets across different currencies.

---

Create a Wallet

import { kernel } from '@platform/sdk-core';

const wallet = await kernel.money().createWallet({
  userId:   '01j9pa5mz700000000000000',
  currency: 'USD',
  label:    'Main USD Wallet',          // optional human-readable label
});

// wallet:
// {
//   walletId:  '01j9paw1t000000000000000',
//   userId:    '01j9pa5mz700000000000000',
//   currency:  'USD',
//   label:     'Main USD Wallet',
//   balance: {
//     available: 0,
//     pending:   0,
//     frozen:    0
//   },
//   createdAt: '2026-04-15T10:30:00.000Z'
// }

POST https://api.septemcore.com/v1/wallets
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "userId":   "01j9pa5mz700000000000000",
  "currency": "USD",
  "label":    "Main USD Wallet"
}

Response 201 Created:

{
  "walletId":  "01j9paw1t000000000000000",
  "userId":    "01j9pa5mz700000000000000",
  "currency":  "USD",
  "label":     "Main USD Wallet",
  "balance": {
    "available": 0,
    "pending":   0,
    "frozen":    0
  },
  "createdAt": "2026-04-15T10:30:00.000Z"
}

Create Parameters

Parameter	Required	Description
userId	✅	Owner of the wallet. Must be an existing user in the tenant.
currency	✅	ISO 4217 currency code (USD, EUR, GBP, JPY, RUB, etc.)
label	☐	Optional human-readable name. Not unique — one user can have two "USD" wallets with different labels.

Multiple wallets with the same currency for the same user are allowed. The module determines which wallet to use by walletId.

---

List Wallets

GET https://api.septemcore.com/v1/wallets?userId=01j9pa5mz700000000000000&currency=USD&limit=20
Authorization: Bearer <access_token>

{
  "data": [
    {
      "walletId":  "01j9paw1t000000000000000",
      "userId":    "01j9pa5mz700000000000000",
      "currency":  "USD",
      "label":     "Main USD Wallet",
      "balance": {
        "available": 10000,
        "pending":   0,
        "frozen":    0
      },
      "createdAt": "2026-04-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": null,
    "hasMore":    false
  }
}

Filter parameters:

Parameter	Description
userId	Filter by owner
currency	Filter by ISO 4217 code
limit	Page size (default 20, max 100)
cursor	Cursor from previous page's nextCursor

---

Get Wallet Details

GET https://api.septemcore.com/v1/wallets/01j9paw1t000000000000000
Authorization: Bearer <access_token>

{
  "walletId":  "01j9paw1t000000000000000",
  "userId":    "01j9pa5mz700000000000000",
  "currency":  "USD",
  "label":     "Main USD Wallet",
  "balance": {
    "available": 10000,
    "pending":   500,
    "frozen":    2500
  },
  "createdAt": "2026-04-15T10:30:00.000Z"
}

---

Get Balance

For high-frequency polling (e.g. live balance display), use the dedicated balance endpoint instead of the full wallet endpoint:

GET https://api.septemcore.com/v1/wallets/01j9paw1t000000000000000/balance
Authorization: Bearer <access_token>

{
  "walletId":  "01j9paw1t000000000000000",
  "currency":  "USD",
  "available": 10000,
  "pending":   500,
  "frozen":    2500,
  "total":     13000,
  "updatedAt": "2026-04-15T10:31:05.000Z"
}

SDK:

const balance = await kernel.money().balance('01j9paw1t000000000000000');
// { available: 10000, pending: 500, frozen: 2500, total: 13000 }

---

Balance Fields

Field	Meaning	Changes on
available	Spendable funds. The only field checked for debit eligibility.	Credit ↑, debit ↓, hold ↓, cancel ↑
pending	Funds received but not yet confirmed (e.g. awaiting payment gateway callback)	External deposit ↑, confirmation ↓
frozen	Funds locked by an active hold. Not spendable.	Hold ↑, confirm ↓, cancel ↓
total	available + pending + frozen — total wallet value	Derived field, read-only

A debit operation checks only available. A user with available: 0 and frozen: 5000 cannot spend — the frozen funds are locked pending a hold confirmation.

---

Multi-Currency

Each wallet is single-currency. Multi-currency support is achieved by creating one wallet per currency for the same user:

const usdWallet = await kernel.money().createWallet({
  userId: '01j9pa5mz700000000000000',
  currency: 'USD',
});

const eurWallet = await kernel.money().createWallet({
  userId: '01j9pa5mz700000000000000',
  currency: 'EUR',
});

Transfers between wallets of different currencies are not supported by the Money Service — currency conversion is the module's responsibility. The module performs the conversion, then calls debit on one wallet and credit on the other, each in their respective currencies.

---

Get Multiple Balances (Batch)

const balances = await kernel.money().balances([
  '01j9paw1t000000000000000',
  '01j9paw2u000000000000000',
]);
// [{ walletId, available, pending, frozen }, ...]

---

Error Reference

Scenario	HTTP	Code
User not found	404	not-found
Invalid currency code (not ISO 4217)	400	validation-error
Wallet not found	404	not-found
Wallet belongs to different tenant	403	forbidden