View beneficiaries

Use this component to show a customer's beneficiaries in an iFrame that Nium hosts. Users page through the list, open details, edit, and start a payout. You don't build list logic, pagination, or drill-down views. Each row has View, Edit, and Pay actions.

This component:

• Shows a paginated table with cursor-based load-more and search by beneficiary name. Each row shows name, email, entity type, and status.
• Opens the embedded payout flow for a beneficiary from any row. No re-selection or navigation is needed.
• Shows demographics, address, contact channels, and linked payment accounts in a detail view.
• Edits in place with the same hosted beneficiary form as Manage beneficiaries, styled with the theme that you pass to the list. The list refreshes after a successful save.
• Adds a Back to Beneficiary List control to every drill-down. It returns to the paginated view.
• Uses the same API version as your client, so coverage and field requirements update as Nium's network evolves.

Live preview

This is the component running against the Nium sandbox with test data. Browse, search, and select beneficiaries to try the list.

Live preview · sandbox

Before you begin

• Complete the Quick start to set up PKCE authorization. Use the scope ['bene-list-form'] when your server requests the authorization code.
• Have the customerHashId of the end user. It scopes the list to that customer's beneficiaries.

Enable the scope for your client

The component uses the bene-list-form scope. Ask your Nium account team to enable it for your client before you integrate.

Quick example

After you call init(), create the beneficiaryList element, mount it, and clean up when you're done.

JavaScript

index.html

<div id="beneficiary-list-container"></div>

client.ts

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

const element = await createElement('beneficiaryList', {
  customerHashId: 'cust-hash-id',   // required
})

element.on('ready', () => setLoading(false))
element.on('error', ({ error }) => showErrorBanner(error.message))

element.mount('#beneficiary-list-container')

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

React

BeneficiaryList.tsx

import { useEffect } from 'react'

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

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

      element.on('ready', () => setLoading(false))
      element.on('error', ({ error }) => showErrorBanner(error.message))
      element.mount('#beneficiary-list-container')
    })()

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

  return <div id="beneficiary-list-container" />
}

Options

createElement('beneficiaryList', options) accepts these options (type NiumBeneficiaryListOptions). The list has no intent modes, prefill fields, or submit configuration. walletHashId and defaultSourceCurrency only affect the payout handoff.

Option	Type	Description
customerHashId	string	Required. Scopes the list to one customer's beneficiaries. The SDK passes it to the hosted iFrame as a URL parameter.
walletHashId	string	Source wallet for the payout flow that starts from a row. The list view ignores it.
defaultSourceCurrency	string	Pre-selected You Send currency (ISO 4217, exactly 3 letters) for that payout flow. An invalid code throws INVALID_CURRENCY_CODE.
theme	NiumTheme	Brands the iFrame with fonts, colors, and border radii. See Theming.

Events

Listen to events with element.on(eventName, handler). It returns a function that removes that listener. To remove a named handler instead, call element.off(event, handler).

• ready: The iFrame loaded and connected to the SDK. Use it to hide a loading spinner or reveal the container.
• resize: The iFrame height changed, for example on a pagination load, a detail view expand, or an edit view open. The SDK adjusts the height for you, so you don't need to handle it.
• error: Authentication failed or an API call failed. Payload: { error: { message: string, code: string } }. Always handle this event. Show the user a clear message or redirect to recovery.

events.ts

// Unsubscribe function (preferred)
const offReady = element.on('ready', () => setLoading(false))
const offError = element.on('error', ({ error }) => showErrorBanner(error.message))

// On component unmount or page leave
offReady()
offError()

// element.off() for a named handler
const onError = ({ error }) => showErrorBanner(error.message)
element.on('error', onError)
element.off('error', onError)

Clean up

Both unmount() and destroy() remove the iFrame from the DOM and clear event listeners. The difference is whether you can reuse the element.

• element.mount(selector): Call once for each element instance after createElement resolves.
• element.unmount(): Removes the iFrame and keeps the instance. Call mount() to show the list again. Use it when you hide the list temporarily in the same session.
• element.destroy(): Removes the iFrame and all listeners permanently. You can't reuse the instance. Use it on page navigation or component unmount.

Initiate a payout from the list

Pay opens the payout flow

The list view doesn't place payouts. When a user selects Pay on an active beneficiary, the iFrame switches to the embedded payout flow with that beneficiary preselected. The iFrame handles the beneficiary selection. Optionally pass walletHashId and defaultSourceCurrency to the list to preconfigure the payout flow.

To run the payout flow on its own, for example with a preselected beneficiaryHashId, see Send payouts.

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, a gating matrix, and 4 ready-to-use example themes.

Next steps

• Send payouts: Start a payout with beneficiaryHashId preselected.
• Manage beneficiaries: Let users add and update beneficiaries.
• Track payouts: Show payout history.