Multicurrency account

Use the Multicurrency account module to embed a customer's wallet home and account statements in your platform, under your brand. Customers view balances and account details, withdraw money, move funds, and download PDF statements without a redirect to a separate banking portal.

Both components share the auth model and theming system of the rest of Nium Embed. The module uses the @nium/nium-sdk package, Proof Key for Code Exchange (PKCE) authorization, and an iFrame.

Components

Component	Element type	Role	Description
Wallet & Accounts	wallet	mcy-wallet-dashboard	The customer's wallet home. Shows the total balance, a card per currency, and account details with copy and PDF download. Includes inline withdraw and move-funds actions. Every section is feature-flagged, so it fits a full wallet page or a balance widget.
Download statements	statementForm	mcy-wallet-statement-generation	Generates and downloads PDF account statements. Offers a monthly list for a selected year, or a custom date range across one or more currencies. Read-only: it doesn't move money, create wallets, or onboard customers.

Theming

Control fonts, colors, and border radius with the NiumTheme object. The Theme customization reference covers all theme properties, a gating matrix, and example themes.

NiumTheme applies to both components. Neither component adds restrictions beyond the standard theming scope.

Integration quick start

Both components follow the same three steps.

1. Generate an authorization code on your server. Call POST /client/{clientHashId}/oauth/authcode with your codeChallenge and the scope for the component: mcy-wallet-dashboard or mcy-wallet-statement-generation. The endpoint returns a short-lived authorizationCode.
2. Initialize and mount on your client. Call init() with env, the authorization code, the codeVerifier, and your clientHashId (as clientId). Call createElement(type, options) with the customerHashId. Call element.mount('#container') to render.
3. Listen to events. Handle element.on('error', ...) for failures. Wallet & Accounts (wallet) also emits submit with { transactionId } when a withdraw (payout) completes. Download statements (statementForm) confirms success only through its snackbar in the iFrame.

Generate the code on your server

Never call the Nium authorization endpoint from the browser. Doing so exposes your x-api-key and clientSecret.

Install the package

npm

terminal

npm install @nium/nium-sdk

yarn

terminal

yarn add @nium/nium-sdk

pnpm

terminal

pnpm add @nium/nium-sdk

Initialize and mount

client.ts

import { init, createElement } from '@nium/nium-sdk';

// authCode comes from your server — never generate it client-side
await init({
  env:            'production',   // or 'sandbox'
  authCode:       '<server-generated-auth-code>',
  codeVerifier:   '<pkce-code-verifier>',
  clientId:       '<your-client-hash-id>',
});

const element = await createElement('<wallet | statementForm>', {
  customerHashId: '<customer-hash-id>',
  // component-specific options — see individual guides
});
element.mount('#sdk-container');

Handle events

client.ts

element.on('ready',  ()    => { /* component has loaded */ });
element.on('error',  (e) => { /* surface error to user */ });

// `wallet` only — fires on completed withdraw
element.on('submit', (e) => { console.log(e.result.transactionId); });

Next steps

The createElement options and event behavior differ per component. statementForm has no submit event. wallet has a customizations object with 12 feature flags, plus minHeight and maxHeight. Open a guide for the full parameter reference:

• Wallet & Accounts: show balances and account details, withdraw money, and move funds.
• Download statements: let customers generate and download PDF statements.