Skip to main content

Payouts

Use the Payouts components to manage beneficiaries, send payouts, respond to compliance requests, and track payouts in your platform. You mount each component with the same createElement call, under your brand.

The module includes:

  • Five components that you can integrate independently.
  • One auth pattern for all components.
  • More than 190 payout corridors.
  • 15 theme properties.

The SDK package is @nium/nium-sdk. Components render in an iFrame and use Proof Key for Code Exchange (PKCE) authorization.

Components​

All five components are live.

  • Manage beneficiaries: Add and manage payout recipients in 190+ corridors. Form fields adjust to each country and payment rail, such as SWIFT, ACH, Pix, and FPS. Real-time account validation is available where supported.
  • View beneficiaries: Browse and search saved beneficiaries. View or edit a recipient, or start a payout to them inside the same iFrame with no form re-entry.
  • Send payouts: Send a payout with a locked live FX quote, review, and submission. It handles rate expiry, beneficiary validation errors, and compliance holds. Your app mounts it and listens for events.
  • Respond to RFIs: Let customers answer compliance Requests for Information (RFIs). Customers submit supporting documents and answers without leaving your platform.
  • Track payouts: Show transaction history in your platform. Users search by transaction ID, filter by period, type, and status, and open any transaction for its status timeline and receipt.

Theming​

Use the NiumTheme object to control colors, fonts, and border radius across Payouts components. Start from a light or dark preset, then set brandColor, surface and text colors, semantic states, fontFamily, and borderRadius. Theme customization lists all 15 theme properties, a gating matrix, and four example themes.

The NiumTheme object applies to Manage beneficiaries, View beneficiaries, Send payouts, and Track payouts.

Respond to RFIs ignores the theme

A separate engine renders Respond to RFIs. It accepts the theme option, but the option has no visual effect.

Quick start​

The same four steps apply to every Payouts component.

Step 1: Generate an auth code on your server​

Your frontend generates the PKCE codeVerifier and codeChallenge. Send the codeChallenge to your server. Your server calls POST /client/{clientHashId}/oauth/authcode with the codeChallenge and the scope for the component. The call returns a short-lived authorizationCode.

Generate the code on your server

Never call the auth endpoint from the browser. It exposes your x-api-key and clientSecret.

Step 2: Install the package​

terminal
npm install @nium/nium-sdk

Step 3: Initialize and mount​

Pass env, the auth code, codeVerifier, and your clientHashId (as clientId) to init(). Then call createElement(type, { customerHashId, … }) with the component's type string. Mount the element in a container div.

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('<type>', {
  customerHashId: '<customer-hash-id>',
  // other component-specific options — see individual guides
});
element.mount('#sdk-container');

Step 4: Handle events​

Listen for submit to capture the output: beneficiaryId and paymentAccountId from Manage beneficiaries, or transactionId from Send payouts. View beneficiaries, Respond to RFIs, and Track payouts emit no submit. Always handle ready and error.

client.ts
element.on('submit', (e) => {
  // payload varies by component — see the guide for e.result shape
  console.log(e.result);
});

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

The createElement type string, required options, and submit payload differ for each component. For the full parameter reference, open the guide for your component in the Components list.

LLM-ready documentation:: llms.txt and llms-full.txt
Was this page helpful?