Wallet Management

Customer wallets are prepaid balances that Monigo can debit at billing time (see Prepaid Billing) or that you can charge programmatically for any purpose. Every wallet operation is recorded with double-entry ledger entries for full auditability.

Core concepts

Concept	Description
Wallet	A balance in a single currency belonging to one customer. A customer can have multiple wallets (one per currency).
Ledger entry	One side of a double-entry accounting record. Every credit/debit creates exactly two entries — one debit and one credit — to keep books balanced.
Virtual account	A dedicated bank account (via Paystack, Flutterwave, or Monnify) that automatically credits the wallet when funds are deposited.

Creating a wallet

Use getOrCreate to ensure a wallet exists for a customer + currency pair. If one already exists, it is returned; otherwise a new wallet with zero balance is created.

curl -X POST https://api.monigo.co/v1/wallets \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_uuid",
    "currency": "NGN"
  }'

wallet, err := client.Wallets.GetOrCreate(ctx, monigo.GetOrCreateWalletRequest{
    CustomerID: "cust_uuid",
    Currency:   "NGN",
})
fmt.Printf("Wallet %s — balance: %s %s\n", wallet.ID, wallet.Balance, wallet.Currency)

const wallet = await client.wallets.getOrCreate({
  customer_id: "cust_uuid",
  currency: "NGN",
});
console.log(`Wallet ${wallet.id} — balance: ${wallet.balance} ${wallet.currency}`);

Listing wallets

All wallets

The org is inferred from your API key.

resp, err := client.Wallets.List(ctx)
for _, w := range resp.Wallets {
    fmt.Printf("  %s — %s %s\n", w.CustomerID, w.Balance, w.Currency)
}

const resp = await client.wallets.list();
for (const w of resp.wallets) {
  console.log(`  ${w.customer_id} — ${w.balance} ${w.currency}`);
}

Filter by customer

You can pass an optional customer_id query parameter to filter wallets:

resp, err := client.Wallets.List(ctx, monigo.ListWalletsParams{
    CustomerID: "cust_uuid",
})

const resp = await client.wallets.list({ customer_id: "cust_uuid" });

Or use the dedicated customer wallets endpoint:

resp, err := client.Wallets.ListByCustomer(ctx, "cust_uuid")

const resp = await client.wallets.listByCustomer("cust_uuid");

Getting a wallet

Fetching a single wallet also returns its virtual accounts.

resp, err := client.Wallets.Get(ctx, "wallet_uuid")
fmt.Printf("Balance: %s\n", resp.Wallet.Balance)
fmt.Printf("Virtual accounts: %d\n", len(resp.VirtualAccounts))

const resp = await client.wallets.get("wallet_uuid");
console.log(`Balance: ${resp.wallet.balance}`);
console.log(`Virtual accounts: ${resp.virtual_accounts.length}`);

Crediting a wallet

Credit adds funds to the wallet. Every credit creates two ledger entries (debit provider, credit wallet) and fires a customer.wallet.topped_up webhook.

curl -X POST https://api.monigo.co/v1/wallets/{wallet_id}/credit \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "10000.00",
    "currency": "NGN",
    "description": "Top-up via payment link",
    "entry_type": "deposit",
    "reference_type": "payment_link",
    "reference_id": "pay_abc123",
    "idempotency_key": "topup_abc123"
  }'

resp, err := client.Wallets.Credit(ctx, walletID, monigo.CreditWalletRequest{
    Amount:         "10000.00",
    Currency:       "NGN",
    Description:    "Top-up via payment link",
    EntryType:      monigo.WalletEntryTypeDeposit,
    ReferenceType:  "payment_link",
    ReferenceID:    "pay_abc123",
    IdempotencyKey: "topup_abc123",
})
fmt.Printf("New balance: %s\n", resp.Wallet.Balance)

import { WalletEntryType } from "@monigo/sdk";

const resp = await client.wallets.credit(walletId, {
  amount: "10000.00",
  currency: "NGN",
  description: "Top-up via payment link",
  entry_type: WalletEntryType.Deposit,
  reference_type: "payment_link",
  reference_id: "pay_abc123",
  idempotency_key: "topup_abc123",
});
console.log(`New balance: ${resp.wallet.balance}`);

Always provide an idempotency_key when crediting wallets. This prevents double-credits if the request is retried. Use a stable reference from your own system (payment ID, transfer reference, etc.).

Entry types for credits

Constant	Value	Use case
`WalletEntryTypeDeposit` / `WalletEntryType.Deposit`	`deposit`	Customer top-up, payment received
`WalletEntryTypeRefund` / `WalletEntryType.Refund`	`refund`	Reversing a previous charge
`WalletEntryTypeAdjustment` / `WalletEntryType.Adjustment`	`adjustment`	Manual balance correction

Debiting a wallet

Debit removes funds from the wallet. Returns a 402 Payment Required error if the balance is insufficient.

resp, err := client.Wallets.Debit(ctx, walletID, monigo.DebitWalletRequest{
    Amount:         "500.00",
    Currency:       "NGN",
    Description:    "Usage charge for March 2026",
    EntryType:      monigo.WalletEntryTypeUsage,
    ReferenceType:  "invoice",
    ReferenceID:    "inv_abc123",
    IdempotencyKey: "debit_inv_abc123",
})
if monigo.IsQuotaExceeded(err) {
    // 402 — insufficient balance
    log.Println("Wallet balance too low")
}

import { MonigoAPIError, WalletEntryType } from "@monigo/sdk";

try {
  const resp = await client.wallets.debit(walletId, {
    amount: "500.00",
    currency: "NGN",
    description: "Usage charge for March 2026",
    entry_type: WalletEntryType.Usage,
    reference_type: "invoice",
    reference_id: "inv_abc123",
    idempotency_key: "debit_inv_abc123",
  });
  console.log(`New balance: ${resp.wallet.balance}`);
} catch (err) {
  if (err instanceof MonigoAPIError && err.statusCode === 402) {
    console.log("Wallet balance too low");
  }
}

Entry types for debits

Constant	Value	Use case
`WalletEntryTypeUsage` / `WalletEntryType.Usage`	`usage`	Metered usage charge
`WalletEntryTypeWithdrawal` / `WalletEntryType.Withdrawal`	`withdrawal`	Customer withdrawal
`WalletEntryTypeAdjustment` / `WalletEntryType.Adjustment`	`adjustment`	Manual balance correction

Transaction history

List paginated ledger entries for a wallet.

resp, err := client.Wallets.ListTransactions(ctx, walletID, monigo.ListTransactionsParams{
    Limit:  25,
    Offset: 0,
})
for _, tx := range resp.Transactions {
    fmt.Printf("  %s %s %s — %s (%s → %s)\n",
        tx.Direction, tx.Amount, tx.Currency,
        tx.Description, tx.BalanceBefore, tx.BalanceAfter)
}

const resp = await client.wallets.listTransactions(walletId, {
  limit: 25,
  offset: 0,
});
for (const tx of resp.transactions) {
  console.log(
    `  ${tx.direction} ${tx.amount} ${tx.currency} — ${tx.description} ` +
    `(${tx.balance_before} → ${tx.balance_after})`
  );
}

Virtual accounts

Virtual accounts are dedicated bank accounts (via Paystack, Flutterwave, or Monnify) that automatically credit the wallet when a customer deposits funds. This enables self-service top-ups without requiring API calls from your backend.

Create a virtual account

va, err := client.Wallets.CreateVirtualAccount(ctx, walletID, monigo.CreateVirtualAccountRequest{
    Provider: monigo.VirtualAccountProviderPaystack,
    Currency: "NGN",
})
fmt.Printf("Account: %s at %s (%s)\n", va.AccountNumber, va.BankName, va.AccountName)

import { VirtualAccountProvider } from "@monigo/sdk";

const va = await client.wallets.createVirtualAccount(walletId, {
  provider: VirtualAccountProvider.Paystack,
  currency: "NGN",
});
console.log(`Account: ${va.account_number} at ${va.bank_name} (${va.account_name})`);

List virtual accounts

resp, err := client.Wallets.ListVirtualAccounts(ctx, walletID)
for _, va := range resp.VirtualAccounts {
    fmt.Printf("  %s — %s %s (%s)\n", va.Provider, va.AccountNumber, va.BankName, va.Currency)
}

const resp = await client.wallets.listVirtualAccounts(walletId);
for (const va of resp.virtual_accounts) {
  console.log(`  ${va.provider} — ${va.account_number} ${va.bank_name} (${va.currency})`);
}

Provider constant	Value
`VirtualAccountProviderPaystack` / `VirtualAccountProvider.Paystack`	`paystack`
`VirtualAccountProviderFlutterwave` / `VirtualAccountProvider.Flutterwave`	`flutterwave`
`VirtualAccountProviderMonnify` / `VirtualAccountProvider.Monnify`	`monnify`

Prepaid billing integration

Wallets are the foundation of Prepaid Billing. When a customer subscribes to a prepaid plan:

Monigo auto-creates a wallet in the plan’s currency
At period-end, Monigo debits the wallet atomically and creates a paid invoice
If the balance is insufficient, the subscription is paused and a subscription.prepaid_balance_insufficient webhook fires
When you credit the wallet and the balance covers the outstanding invoice, Monigo auto-resumes the subscription

This means you only need to handle wallet top-ups — Monigo takes care of billing, pausing, and resuming automatically.

Real-time billing

A plan with billing_mode: "realtime" debits the wallet in near-real-time (within ~5 seconds) as usage accrues, rather than once at the end of the period. It supports every pricing model (per_unit, tiered, volume, package, cap): as events arrive, Monigo recomputes the cumulative charge for the period and debits the wallet for the marginal difference.

Continuous metering — each new batch of usage triggers a reconcile that charges only the incremental amount, so the wallet always reflects what the customer owes so far.
Pause on empty — when the wallet can no longer cover the next marginal charge, the subscription is paused, metering stops, and a subscription.prepaid_balance_insufficient webhook fires.
Auto-resume on top-up — crediting the wallet reactivates the subscription, reconciles any usage that accrued while paused, and resumes metering automatically.
One paid summary invoice per period — at period-end Monigo emits a single paid invoice that itemizes the period’s usage per metric, with the total equal to what was already debited in real time. No additional debit happens at close — the invoice is purely a reporting artifact.

Realtime plans must be collection plans (a realtime payout plan is rejected). As with prepaid, you only need to handle wallet top-ups — metering, pausing, resuming, and the period-end invoice are all automatic.

Inline funding session

When a customer wants to top up their own wallet directly in your portal UI (without a server-side redirect), set "inline": true in the funding request. Monigo returns a WalletFundingSession containing only publishable credentials — no secret keys are ever exposed.

The provider webhook remains the source of truth for crediting the wallet. Do not credit the wallet client-side after the payment completes — Monigo handles that automatically when the provider sends its payment notification.

Request

curl -X POST https://api.monigo.co/v1/portal/wallets/{wallet_id}/fund \
  -H "Authorization: Bearer pk_portal_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "5000.00",
    "currency": "NGN",
    "inline": true
  }'

const session = await portalClient.wallets.fund(walletId, {
  amount: "5000.00",
  currency: "NGN",
  inline: true,
});

Response — `WalletFundingSession`

{
  "provider": "paystack",
  "reference": "mng_wf_01j...",
  "amount": "5000.00",
  "currency": "NGN",
  "email": "customer@example.com",
  "customer_name": "Ada Lovelace",
  "public_key": "pk_live_...",
  "access_code": "0pepr...",
  "authorization_url": "https://checkout.paystack.com/0pepr..."
}

Field	Type	Description
`provider`	string	Payment provider (`paystack`, `stripe`, `monnify`)
`reference`	string	Monigo-generated payment reference
`amount`	string	Funding amount
`currency`	string	ISO 4217 currency code
`email`	string	Customer email address
`customer_name`	string	Customer display name
`public_key`	string	Provider publishable key (safe for the browser)
`access_code`	string	Paystack access code — pass to `PaystackPop.newTransaction()`
`client_secret`	string	Stripe client secret — pass to Stripe.js `confirmPayment()`
`contract_code`	string	Monnify contract code — used to initialise the Monnify SDK
`meta`	object	Provider-specific extra fields
`authorization_url`	string	Fallback redirect URL (also populated for inline sessions)

Using the session in the browser

Pass the session fields directly to your provider’s inline SDK. Only the fields relevant to the active provider will be populated.

const handler = PaystackPop.setup({
  key: session.public_key,
  email: session.email,
  amount: parseFloat(session.amount) * 100, // kobo
  ref: session.reference,
  access_code: session.access_code,
  onSuccess: () => { /* wallet credited by webhook — just refresh balance */ },
});
handler.openIframe();

const stripe = Stripe(session.public_key);
await stripe.confirmPayment({
  clientSecret: session.client_secret,
  elements,
});

Only publishable keys are returned in the inline session. Secret keys live exclusively on the Monigo backend and are never forwarded to the portal.

The <WalletWidget> component is a self-contained UI that shows the customer’s live balance and opens the configured payment provider’s inline checkout when they click Fund wallet. Drop it anywhere inside a <MonigoProvider> — no extra state management required.

Installation

npm install @monigo/svelte @monigo/tokens

Usage

<script>
  import { MonigoProvider, WalletWidget } from '@monigo/svelte'
  import '@monigo/tokens/monigo.css'

  // portalToken is the raw hex string from PortalToken.token — mint it server-side.
  let { portalToken, walletId, currency } = $props()
</script>

<MonigoProvider {portalToken}>
  <WalletWidget {walletId} {currency} />
</MonigoProvider>

import { MonigoProvider, WalletWidget } from '@monigo/react'
import '@monigo/tokens/monigo.css'

export function AgentWallet({ portalToken, walletId, currency }) {
  return (
    <MonigoProvider portalToken={portalToken}>
      <WalletWidget walletId={walletId} currency={currency} />
    </MonigoProvider>
  )
}

<script setup>
import { MonigoProvider, WalletWidget } from '@monigo/vue'
import '@monigo/tokens/monigo.css'

defineProps(['portalToken', 'walletId', 'currency'])
</script>

<template>
  <MonigoProvider :portal-token="portalToken">
    <WalletWidget :wallet-id="walletId" :currency="currency" />
  </MonigoProvider>
</template>

Minting a portal token (server-side)

MonigoProvider expects the raw token string (PortalToken.token) — not the full object returned by the SDK. Mint it on the server so your secret API key is never exposed to the browser.

TypeScript (SvelteKit server load)

import { MonigoClient } from '@monigo/sdk'
import { env } from '$env/dynamic/private'

const monigo = new MonigoClient({ apiKey: env.MONIGO_API_KEY })

export const load = async () => {
  const portalToken = await monigo.portalTokens.create({
    customer_external_id: 'your-customer-external-id',
    label: 'Wallet widget session',
  })
  return { portalToken: portalToken.token }
}

portalTokens.create() accepts a customer_external_id (the external_id you set when creating the customer) — not the internal Monigo UUID. The SDK infers the organisation from your API key.

Props

Prop	Type	Default	Description
`walletId`	`string`	—	UUID of the wallet to display and fund. Required.
`currency`	`string`	—	ISO 4217 currency code (e.g. `NGN`). Required.
`presets`	`number[]`	`[1000, 5000, 10000]`	Quick-pick funding amounts shown as chips.
`pollIntervalMs`	`number`	`8000`	How often (ms) the widget re-fetches the live balance.
funded callback	`(reference: string) => void`	—	Called with the provider payment reference after a successful top-up. Svelte: `onfunded`; React: `onFunded`; Vue: `@funded`.
error callback	`(err: unknown) => void`	—	Called when a balance fetch or checkout fails. Svelte: `onerror`; React: `onError`; Vue: `@error`.
`class`	`string`	—	Extra CSS classes applied to the widget wrapper (Svelte/Vue; React uses `className`).

Live balance — polls /portal/wallets/{walletId} every pollIntervalMs milliseconds and formats the balance with Intl.NumberFormat.
Inline checkout — calls the portal funding endpoint to get a WalletFundingSession and launches Paystack, Stripe, Flutterwave, or Monnify inline. Only the relevant provider fields are populated (see Inline funding session).
Auto-refresh — after a successful payment, the widget immediately polls for the updated balance, so the customer sees the new total without a page reload.
Usage debits — as your backend debits the wallet for metered usage (via wallets.debit()), the polling loop picks up the reduced balance automatically.

Never credit the wallet client-side after a payment completes. The provider webhook is the source of truth — Monigo credits the wallet automatically when the provider sends its payment notification.

Full working example

See platform/samples/ai-agent-wallet for a complete SvelteKit app that mints a portal token on the server, renders the widget, and includes a form action that debits the wallet to simulate agent token usage.

Webhook events

Event	When fired
`customer.wallet.topped_up`	Wallet credited successfully
`subscription.prepaid_balance_insufficient`	Prepaid billing failed — wallet balance too low
`invoice.paid`	Prepaid invoice paid via wallet debit

Prepaid Billing — end-to-end prepaid subscription flow
Invoice Lifecycle — invoice states and transitions
Subscription Lifecycle — pause, resume, and cancel behavior
Webhooks — receiving billing events

Get Started

Concepts

Guides

SDKs

Integrations

API Reference

Wallet Management

Core concepts

Creating a wallet

Listing wallets

All wallets

Filter by customer

Getting a wallet

Crediting a wallet

Entry types for credits

Debiting a wallet

Entry types for debits

Transaction history

Virtual accounts

Create a virtual account

List virtual accounts

Prepaid billing integration

Real-time billing

Inline funding session

Request

Response — `WalletFundingSession`

Using the session in the browser

Drop-in wallet widget (inline funding + live balance)

Installation

Usage

Minting a portal token (server-side)

Props

What the widget does

Full working example

Webhook events

​Core concepts

​Creating a wallet

​Listing wallets

​All wallets

​Filter by customer

​Getting a wallet

​Crediting a wallet

​Entry types for credits

​Debiting a wallet

​Entry types for debits

​Transaction history

​Virtual accounts

​Create a virtual account

​List virtual accounts

​Prepaid billing integration

​Real-time billing

​Inline funding session

​Request

​Response — WalletFundingSession

​Using the session in the browser

​Drop-in wallet widget (inline funding + live balance)

​Installation

​Usage

​Minting a portal token (server-side)

​Props

​What the widget does

​Full working example

​Webhook events

​Related

Core concepts

Creating a wallet

Listing wallets

All wallets

Filter by customer

Getting a wallet

Crediting a wallet

Entry types for credits

Debiting a wallet

Entry types for debits

Transaction history

Virtual accounts

Create a virtual account

List virtual accounts

Prepaid billing integration

Real-time billing

Inline funding session

Request

Response — `WalletFundingSession`

Using the session in the browser

Drop-in wallet widget (inline funding + live balance)

Installation

Usage

Minting a portal token (server-side)

Props

What the widget does

Full working example

Webhook events

Related