Skip to main content

Foreign exchange

Use the foreign exchange (FX) module to let customers convert balance between the currencies in their Nium multicurrency wallet. You mount it with the same createElement call, and it shares the auth model and theming of every other Nium Embed component.

The module provides:

  • One drop-in component
  • One auth pattern shared with all Nium Embed components
  • Live FX quoting on every conversion
  • 15 theme properties

Components​

  • Convert currencies: component type conversionForm. It's a guided three-step flow: enter the amount and currency pair, review a live FX quote, and confirm. It converts balance between the currencies in a customer's wallet. It doesn't send money to a beneficiary or onboard customers.

Customization and theming​

Use the NiumTheme object to control fonts, colors, and border radius for conversionForm. It supports all 15 properties, as do beneficiaryForm, payoutForm, transactionHistoryForm, and the beneficiary list. See Theme customization for all 15 theme properties, a gating matrix, and four example themes.

Quick start​

Every Nium Embed component uses the same pattern.

Step 1: Generate an auth code on your server​

Call POST /client/{clientHashId}/oauth/authcode with your codeChallenge and the scope mcy-wallet-move-funds. The call returns a short-lived authorizationCode.

Generate the code on your server

Never call the auth endpoint from the browser. It exposes your API credentials.

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('conversionForm', options) and element.mount('#container').

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('conversionForm', {
  customerHashId: '<customer-hash-id>',   // the only required property
});
element.mount('#conversion-container');

Step 4: Handle events​

Use element.on('submit', ...) to capture the settled transfer. It fires when the user closes the summary screen after a successful conversion, and e.result.transfer has the converted amounts and the exchange rate. cancel fires if the user closes the flow without converting. Always handle error as well.

client.ts
element.on('submit', (e) => {
  // e.result.transfer carries the settled conversion figures
  console.log(e.result.transfer);
});

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

Next steps​

  • Convert currencies: review the createElement options, the submit payload shape, and the internal service calls.
  • Quick start: set up the shared PKCE authorization.
LLM-ready documentation:: llms.txt and llms-full.txt
Was this page helpful?