Onboard customers

Use this component to onboard a business or an individual into Nium from your application. It shows Nium's customer initial-enquiry and onboarding form, which collects the information Nium needs to open and verify a customer. You can tie the session to your own identifier through externalId.

This component creates and progresses an onboarding session only. It doesn't create beneficiaries, wallets, or transactions. Downstream components (Send payouts, Wallet & Accounts, Track payouts) become available once the customer is onboarded.

This component:

• Shows a form generated from Nium's compliance and product configuration for your client.
• Uses your standard Proof Key for Code Exchange (PKCE) authorization. You don't need a per-customer code to start onboarding.
• Starts a new session, or resumes one when you pass externalId.
• Runs in embedded mode automatically. You don't need a configuration flag.
• Uses the same API version as your client. When you upgrade Nium APIs, it reflects the updated requirements.

Live preview

This is the component running against the Nium sandbox with test data. Step through the form to try customer onboarding.

Live preview · sandbox

Before you begin

• Complete the Quick start to set up PKCE authorization. Use the scope ['customer-onboarding-form'] when your server requests the authorization code. Confirm the role name customer-onboarding-form with your Nium integration contact for your environment.
• Optional: have an externalId for the customer. Pass it to resume an onboarding session. Omit it to start a new one.

Quick example

After you call init(), create the customerOnboardingForm element, mount it, and clean up when you're done. No option is required.

JavaScript

index.html

<div id="customer-onboarding-container"></div>

client.ts

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

const element = await createElement('customerOnboardingForm', {
  externalId: 'your-customer-reference', // optional: resumes an existing session
  customizations: { minHeight: 700 },    // recommended: the iFrame can't auto-resize after handoff
})

element.on('ready', () => spinner.hide())
element.on('error', (e) => console.error(e.error.message))

element.mount('#customer-onboarding-container')

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

React

CustomerOnboarding.tsx

import { useEffect } from 'react'

export function CustomerOnboarding({ externalId }: { externalId?: string }) {
  useEffect(() => {
    let element: { destroy(): void } | undefined
    let cancelled = false

    ;(async () => {
      const { createElement } = await import('@nium/nium-sdk')
      element = await createElement('customerOnboardingForm', {
        externalId,
        customizations: { minHeight: 700 },
      })
      if (cancelled) return element.destroy()

      element.on('error', (e) => console.error(e.error.message))
      element.mount('#customer-onboarding-container')
    })()

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

  return <div id="customer-onboarding-container" />
}

Mount each element only once. This component shows a loading state during the token exchange and session creation.

Choose how users reach the form

externalId supports two patterns.

• New customer sign-up. A new user signs up in your product. Mount this component with no externalId. Onboarding starts immediately.
• Resume an incomplete onboarding. The user left before finishing. Mount this component again with the same externalId. The user resumes where they left off. If you omit it, a new session always starts.

Options

createElement('customerOnboardingForm', options) accepts these options (type NiumCustomerOnboardingProperties). All are optional. Calling createElement('customerOnboardingForm') with no options starts a new onboarding session.

Option	Type	Description
externalId	string	Your reference for the customer. Resumes an existing onboarding session. Omit to start a new one, and Nium generates a new identifier.
customizations.minHeight	number	iFrame height in px. Default 400. Set it to the height you want. The form scrolls inside the iFrame beyond it.
customizations.maxHeight	number	Optional cap on the iFrame height in px.
theme	NiumTheme	Styles the initial loading screen only. See Theming.

Unlike Manage beneficiaries, this component has no intent option. It always runs through Nium's compliance rendering layer, so your server can't take over the API call.

Events

Listen to lifecycle events with element.on(eventName, handler). After the SDK exchanges the auth code, the iFrame hands off to Nium's hosted onboarding app on a separate origin. The SDK accepts messages only from the hosted-form origin, so only ready and setup-stage error events reach your page.

• ready: The iFrame is fully rendered. Remove loading states or reveal the container.
• resize: Fires only while the initial loading screen shows. After the handoff, the iFrame can't report its height. Set customizations.minHeight to the height you want. Payload: { height: number }.
• error: The token exchange failed (TOKEN_EXCHANGE_FAILED), clientId is missing (MISSING_IDS), session creation failed (SESSION_CREATION_FAILED), or the iFrame failed to load. Errors inside the onboarding form appear to the user but aren't sent to your page. Always handle this event. Payload: { error: { message: string, code: string } }.

No submit or cancel event

This component never emits submit or cancel, unlike other Nium Embed components, and element.submit() isn't supported. It rejects with SUBMIT_UNSUPPORTED. When the customer completes the form, the session transitions. You track its status on your server through your integration's standard onboarding status mechanism. See Technical architecture.

Clean up

Call element.destroy() on route change, modal close, or component unmount. It removes the iFrame and detaches all listeners.

Theming

The theme styles only the loading screen

Nium's compliance rendering layer renders this component, the same engine that renders Request for Information forms. The NiumTheme object described in Theme customization applies to every other Nium Embed component. Here it styles only the initial loading screen. The onboarding form itself isn't themed.

Technical architecture

This component uses a session-based redirect architecture inside the iFrame.

1. Token exchange. It exchanges the PKCE authorization code for an access token through Nium's OAuth2 token endpoint.
2. Session creation. It uses the access token to create an onboarding session scoped to {clientId}, with featureType: 'customer_onboarding_form'. It passes externalId to the session creation endpoint. If you omit it, an identifier is generated and a new session starts.
3. Embedded redirect. The iFrame redirects internally to the onboarding form that Nium's compliance rendering layer hosts (/customers/initial-enquiry?sessionId={sessionId}). The form renders in embedded mode.
4. Form submission. When the user completes the form, the form processes the submission. Your backend is notified through your integration's normal session-status mechanism.

Onboarding sessions last 30 days, so a user can return and resume with the same externalId.

Troubleshooting

Common issues

Issue	Likely cause and fix
Session creation failed	Check that the clientId in init() matches the clientHashId the authorization code was issued for. Check that the externalId, if supplied, belongs to your client.
Form starts over instead of resuming	Pass the same externalId you used when you created the session. Omitting it always starts a new session.
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 customer-onboarding-form for your environment.

For more help, contact your Nium integration team.