Download statements

Use this component to let customers generate and download account statements for their Nium wallet from your application. Customers pick a monthly statement for a selected year, or request a statement for a custom date range and a chosen set of currencies. Each statement is a PDF.

The component is read-only. It doesn't move money, create wallets, or onboard customers. It:

• Lists the monthly statements for a selected year, each with a Download action.
• Lets customers select Generate Statement to request a statement for any start and end date.
• Lists the currencies in the customer's wallet. A statement covers one, several, or all of them.
• Downloads the PDF directly in the browser, under a generated file name based on the customer and period. On success, the iFrame shows the snackbar Account statement downloaded.

Live preview

This is the component running against the Nium sandbox with test data. Pick a monthly statement or select Generate Statement to try a custom range.

Live preview · sandbox

Before you begin

• Complete the Quick start to set up PKCE authorization. Use the scope ['mcy-wallet-statement-generation'] when your server requests the authorization code. Confirm the role name with your Nium integration contact for your environment.
• Have the customerHashId of the customer whose statements you generate. The wallet and its currencies resolve from this identifier, so you don't pass a wallet identifier.

You don't need a per-statement code. The component uses your standard PKCE session.

Quick example

After you call init(), create the statementForm element and mount it. customerHashId is the only required option.

JavaScript

index.html

<div id="statement-container"></div>

client.ts

const { createElement } = await import('@nium/nium-sdk')

const element = await createElement('statementForm', {
  customerHashId: '<customer-hash-id>', // required
})

element.on('ready', () => setLoading(false))
element.on('error', (e) => showErrorToast(e.error.message))

element.mount('#statement-container')

// When you're done, for example on a route change
element.destroy()

React

StatementForm.tsx

import { useEffect } from 'react'

export function StatementForm({ customerHashId }: { customerHashId: string }) {
  useEffect(() => {
    let element: { destroy(): void } | undefined
    let cancelled = false

    ;(async () => {
      const { createElement } = await import('@nium/nium-sdk')
      element = await createElement('statementForm', { customerHashId })
      if (cancelled) return element.destroy()

      element.on('error', (e) => console.error('Statement error:', e.error.message))
      element.mount('#statement-container')
    })()

    return () => {
      cancelled = true
      element?.destroy()
    }
  }, [customerHashId])

  return <div id="statement-container" />
}

On mount, the component shows a loading state while it exchanges the token and loads the customer and wallet details.

Options

createElement('statementForm', options) accepts these options (type NiumStatementFormProperties).

Option	Type	Description
customerHashId	string	Required. Customer whose statements are generated.
theme	NiumTheme	Visual customizations. See Theming.

Unlike wallet, this component doesn't accept a customizations object. It has no sections or buttons to toggle.

Events

Listen to events with element.on(eventName, handler). It returns a function that removes that listener. Call it when you remove the component to prevent memory leaks.

• ready: The iFrame is fully rendered. Use it to remove loading states or reveal the container.
• resize: The iFrame content height changed. Use it to size the container. Payload: { height: number }.
• error: The token exchange failed, the session expired (AUTH_EXPIRED), or the iFrame failed to load. Customer or wallet lookup failures and statement request failures appear inside the iFrame only. Your page doesn't receive them. Payload: { error: { message: string, code: string } }.

No submit event

The component has no submit event. The browser downloads the statement directly, so no event carries a result payload. The snackbar Account statement downloaded in the iFrame is the only success confirmation. Use error to show setup and session failures in your own UI. Lookup and statement failures show to the user in the iFrame.

How it works

The component renders Nium's UI inside the iFrame, with no redirect to a hosted form. The iFrame does the following:

1. Exchanges the token. Swaps the PKCE authorization code for an access token through /api/niam-service/oauth2/token.
2. Looks up the customer and wallet. Loads the customer's details and wallet currencies through Nium's customer and wallet-service APIs.
3. Requests the statement. When the user submits a monthly row or a custom range, calls GET /api/wallet-service/api/v1/client/{clientId}/customer/{customerId}/accounts/statement with startDate, endDate, and the selected currencies.
4. Downloads the PDF. Returns the response as a PDF. The browser downloads it under a generated file name based on the customer name and period.

Keep these behaviors in mind:

• The monthly list comes from the selected year. Past months are offered for download.
• A custom-range statement needs at least one currency.
• Lookup and statement-request failures appear as an in-form message only. The error event covers token exchange, session expiry, and iFrame load.

Clean up

Call element.destroy() on route change or page leave. It removes the iFrame and clears all event listeners. The instance can't be reused.

To hide the component temporarily, call element.unmount() instead. It removes the iFrame and clears listeners but keeps the instance. Call element.mount('#statement-container') to show it again. Mount each instance only once at a time.

Troubleshooting

Issue	Likely cause and fix
No currencies listed	Check that the customerHashId is correct and that the customer has an active wallet with at least one currency.
Download does nothing	Check that the embedding page doesn't block downloads started by the iFrame. If you set the sandbox attribute yourself, the iFrame needs the allow-downloads permission.
Empty statement	The period might have no transactions for the chosen currencies. Widen the date range or select more currencies.
Component not rendering	Check the browser console for error events. Make sure the container element exists before you mount.
Incorrect role	Confirm with your Nium integration contact that you use the role name mcy-wallet-statement-generation for your environment.

For more help, contact your Nium integration team.

Theming

Pass a NiumTheme object in the theme option to control fonts, colors, input styles, and border radius. The Theme customization reference documents all 15 theme properties and 4 ready-to-use example themes.

Next steps

• Wallet & Accounts: pair this component with the wallet for a single account screen. The customerHashId that resolves statements here also resolves the wallet, and both components use the same auth pattern.
• Theme customization: match the component to your brand.