@mygigsters/beneficiary-sdk

Embed a secure beneficiary management form into any web application — with support for Indian bank accounts and global payments via Airwallex.

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Quick Start
• Module Formats
• Usage Examples
  • ES Modules (Recommended)
  • CommonJS
  • CDN / Browser Script Tag
  • Auto-Initialize via Script Attribute
• Configuration Reference
• API Reference
  • init(config)
  • show()
  • hide()
  • setTheme(mode)
  • destroy()
  • getInstance()
• Callback Reference
• Payment Flows
  • Indian Entity (Account No. + IFSC)
  • Australia / Global Entity (Airwallex)
• Environments
• Theming
• Error Handling
• Security
• TypeScript
• Troubleshooting
• Changelog

Overview

The MyGigsters Beneficiary SDK renders a secure, self-contained modal form that lets your users add payment beneficiaries. The SDK:

• Authenticates with the MyGigsters backend using your API credentials.
• Automatically detects which payment flows are enabled for your account (paymentsIndia flag).
• Renders inside an isolated Shadow DOM, so your host page styles never leak in and vice versa.
• Uses PKCE (Proof Key for Code Exchange) to securely hand off to the Airwallex payment platform for non-Indian bank accounts.

Features

• Indian bank accounts — Account number + IFSC validation with real-time verification.
• Global payments — Airwallex-powered form for Australian and international beneficiaries.
• Shadow DOM isolation — No CSS conflicts with your app.
• Light & Dark themes — Toggle at init time or at runtime.
• Zero React dependency — Works in any JavaScript app (React, Vue, Angular, plain HTML).
• Multiple module formats — ESM, CJS, UMD.
• Auto-init via data-mygigsters-config HTML attribute — no JavaScript required.

Requirements

| Requirement | Version | |-------------|---------| | Browser | Chrome 80+, Firefox 78+, Safari 14+, Edge 80+ | | Node.js (build/dev only) | ≥ 14.0.0 | | React (optional) | ≥ 18.0.0 |

Note: window.crypto.subtle must be available. All modern browsers support this. It is unavailable over plain http:// — always serve your page over HTTPS (or localhost for development).

Installation

# npm
npm install @mygigsters/beneficiary-sdk

# yarn
yarn add @mygigsters/beneficiary-sdk

# pnpm
pnpm add @mygigsters/beneficiary-sdk

Quick Start

1. Add a container element in your HTML:

<div id="beneficiary-form"></div>

2. Initialize the SDK:

import { MygigstersBeneficiarySDK } from '@mygigsters/beneficiary-sdk';

const sdk = new MygigstersBeneficiarySDK();

await sdk.init({
  apiKey:      'your_api_key',
  apiSecret:   'your_api_secret',
  env:         'demo',
  containerId: 'beneficiary-form',
  onSuccess: (data) => console.log('Beneficiary saved!', data),
  onError:   (err)  => console.error('Error:', err.message),
  onClose:   ()     => console.log('Modal closed'),
});

The modal opens automatically after init() resolves.

Module Formats

| Format | Path | Use Case | |--------|------|----------| | ESM | dist/index.esm.js | Modern bundlers (Vite, Webpack 5, Rollup) | | CommonJS | dist/index.cjs.js | Node.js / require() environments | | UMD | dist/index.umd.js | Browser <script> tag / CDN | | TypeScript | dist/index.d.ts | Type definitions |

Usage Examples

ES Modules (Recommended)

import { MygigstersBeneficiarySDK } from '@mygigsters/beneficiary-sdk';

const sdk = new MygigstersBeneficiarySDK();

await sdk.init({
  apiKey:      'your_api_key',
  apiSecret:   'your_api_secret',
  env:         'demo',           // 'demo' | 'prod'
  containerId: 'beneficiary-form',
  mode:        'dark',           // optional: 'dark' (default) | 'light'
  onSuccess: (data) => {
    console.log('✅ Beneficiary added:', data);
    // data.success === true
    // data.message contains a success message
  },
  onError: (err) => {
    console.error('❌ Error:', err.message);
  },
  onClose: () => {
    console.log('Modal closed by user');
  },
});

CommonJS

const { MygigstersBeneficiarySDK } = require('@mygigsters/beneficiary-sdk');

const sdk = new MygigstersBeneficiarySDK();

sdk.init({
  apiKey:      'your_api_key',
  apiSecret:   'your_api_secret',
  env:         'demo',
  containerId: 'beneficiary-form',
  onSuccess: (data) => console.log('Success:', data),
  onError:   (err)  => console.error('Error:', err.message),
  onClose:   ()     => console.log('Closed'),
});

CDN / Browser Script Tag

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>My App</title>
</head>
<body>

  <!-- 1. Mount target -->
  <div id="beneficiary-form"></div>

  <!-- 2. Trigger button (optional) -->
  <button onclick="openBeneficiaryForm()">Add Beneficiary</button>

  <!-- 3. Load the SDK -->
  <script src="https://cdn.jsdelivr.net/npm/@mygigsters/beneficiary-sdk/dist/index.umd.js"></script>

  <script>
    async function openBeneficiaryForm() {
      await MygigstersBeneficiary.init({
        apiKey:      'your_api_key',
        apiSecret:   'your_api_secret',
        env:         'demo',
        containerId: 'beneficiary-form',
        mode:        'light',
        onSuccess: (data) => console.log('✅ Success:', data),
        onError:   (err)  => console.error('❌ Error:', err.message),
        onClose:   ()     => console.log('Closed'),
      });
    }
  </script>

</body>
</html>

CDN global: The UMD build exposes window.MygigstersBeneficiary (not MygigstersBeneficiarySDK).

Auto-Initialize via Script Attribute

You can pass configuration directly on the <script> tag — no extra JavaScript needed:

<div id="beneficiary-form"></div>

<script
  src="https://cdn.jsdelivr.net/npm/@mygigsters/beneficiary-sdk/dist/index.umd.js"
  data-mygigsters-config='{
    "apiKey":      "your_api_key",
    "apiSecret":   "your_api_secret",
    "env":         "demo",
    "containerId": "beneficiary-form",
    "mode":        "light"
  }'
></script>

The SDK reads data-mygigsters-config on DOMContentLoaded and calls init() automatically. Callbacks are not available through this approach — use the JavaScript API instead if you need onSuccess / onError / onClose.

Configuration Reference

Pass these options to init():

| Parameter | Type | Required | Default | Description | |-----------|------|:--------:|---------|-------------| | apiKey | string | ✅ | — | UUID-style API key issued by MyGigsters | | apiSecret | string | ✅ | — | One-time API secret (shown once at creation) | | env | 'demo' \| 'prod' | ✅ | 'prod' | Target environment | | containerId | string | ✅ | — | id of the DOM element to mount the SDK into | | mode | 'light' \| 'dark' | ❌ | 'light' | UI color theme | | onSuccess | (data) => void | ❌ | no-op | Fired after the beneficiary is saved successfully | | onError | (error) => void | ❌ | console.error | Fired on any SDK or network error | | onClose | () => void | ❌ | no-op | Fired when the user closes the modal |

API Reference

init(config)

Authenticates with the MyGigsters backend, builds the Shadow DOM modal, and automatically calls show().

import { MygigstersBeneficiarySDK } from '@mygigsters/beneficiary-sdk';

const sdk = new MygigstersBeneficiarySDK();

await sdk.init(config);
// or, via CDN:
await MygigstersBeneficiary.init(config);

• Returns: Promise<void>
• Throws: if apiKey, apiSecret, or containerId are missing; if the container element is not found; or if authentication fails.
• Each SDK instance maintains its own internal state.
• CDN builds expose a singleton instance automatically.

show()

Shows the beneficiary modal. Called automatically by init(), but can be called again after hide().

sdk.show();

Throws Error: SDK not initialized. Call init() first. if called before init().

hide()

Hides the modal without destroying the SDK instance. The form state is preserved.

sdk.hide();

setTheme(mode)

Switch the UI theme at runtime — no need to re-initialize.

sdk.setTheme('dark');  // or 'light'

// Example: sync with OS preference
const mq = window.matchMedia('(prefers-color-scheme: dark)');
mq.addEventListener('change', (e) => {
 sdk.setTheme(e.matches ? 'dark' : 'light');
});

destroy()

Removes the modal from the DOM and resets all internal state. Call this when navigating away or unmounting the host component.

sdk.destroy();

getInstance() (CDN only)

Returns the underlying SDK instance for advanced use.

const sdk = MygigstersBeneficiary.getInstance();

Callback Reference

onSuccess(data)

Called after a beneficiary is saved and the success screen is shown (≈ 2 seconds after save).

onSuccess: (data) => {
  // data.success  → true
  // data.message  → server confirmation message
  console.log('Saved!', data);
}

onError(error)

Called when any error occurs — authentication failures, network errors, or validation rejections from the server.

onError: (error) => {
  // error is a standard JS Error object
  console.error(error.message);
}

onClose()

Called when the user dismisses the modal (close button, Cancel button, or clicking the backdrop).

onClose: () => {
  // Re-show a trigger button, update UI state, etc.
}

Payment Flows

The SDK automatically selects the correct flow based on your account's paymentsIndia flag returned during authentication.

Indian Entity (Account No. + IFSC)

The user fills in:

• Beneficiary Name — full name
• Email — valid email address
• Beneficiary Type — Individual or Company
• Account Name — name on the bank account
• Account Number + Confirm Account Number
• IFSC Code — 11-character code; verified in real time against the MyGigsters backend
• Account Type — Savings or Current

Australia / Global Entity (Airwallex)

The user fills in:

1. Beneficiary Name, Email, Beneficiary Type → Click Load Form
2. The SDK performs a PKCE handshake with the MyGigsters backend and mounts an Airwallex beneficiary form iframe.
3. The user fills in bank details inside the Airwallex iframe → Click Save Beneficiary
4. The SDK submits the Airwallex form, receives the bank token, and POSTs to POST /api/v1/save-other-beneficiary with entityType: 'AUSTRALIA'.

The Airwallex iframe is isolated from the Shadow DOM's innerHTML — it will not be destroyed by re-renders or error banners.

Theming

Set mode: 'light' or mode: 'dark' in the config object. The theme applies to both the SDK's own UI and the embedded Airwallex form.

You can also switch themes after initialization using setTheme().

// Toggle dark mode on a button click
const sdk = new MygigstersBeneficiarySDK();

document.getElementById('toggle-theme').addEventListener('click', () => {
  sdk.setTheme(
    document.body.classList.toggle('dark') ? 'dark' : 'light'
  );
});

Error Handling

Wrap init() in a try/catch to handle initialization errors:

try {
 const sdk = new MygigstersBeneficiarySDK();

await sdk.init({ ... });
} catch (err) {
  // Common errors:
  // "apiKey is required"MygigstersBeneficiarySDK.setTheme(
  // "Container element with ID '...' not found"
  // "Invalid API credentials: Please check your apiKey and apiSecret."
  // "Authentication failed: ..."
  console.error('SDK failed to initialize:', err.message);
}

Runtime errors (network failures, server rejections) are surfaced via the onError callback and displayed inline in the form. You do not need to wrap show(), hide(), or destroy() in try/catch under normal circumstances.

Security

• Credentials are never stored in localStorage or sessionStorage. The auth token lives in memory only.
• Authentication uses HTTP Basic Auth (base64(apiKey:apiSecret)) over HTTPS. Never expose your apiSecret in client-side code that is committed to a public repository — use environment variables or a backend-for-frontend pattern.
• PKCE is implemented using crypto.subtle.digest('SHA-256') (native Web Crypto API) — no third-party crypto library is used for this flow.
• Shadow DOM (mode: 'closed') prevents host-page scripts from reaching into the SDK's DOM.

TypeScript

Type definitions are included at dist/index.d.ts. Import the SDK as usual:

import { MygigstersBeneficiarySDK } from '@mygigsters/beneficiary-sdk';

interface BeneficiaryConfig {
  apiKey: string;
  apiSecret: string;
  env: 'demo' | 'prod';
  containerId: string;
  mode?: 'light' | 'dark';
  talentId?: string;
  onSuccess?: (data: Record<string, unknown>) => void;
  onError?: (error: Error) => void;
  onClose?: () => void;
}

const sdk = new MygigstersBeneficiarySDK();

await sdk.init({
  apiKey: process.env.MYGIGSTERS_API_KEY!,
  apiSecret: process.env.MYGIGSTERS_API_SECRET!,
  env: 'prod',
  containerId: 'beneficiary-form',
} satisfies BeneficiaryConfig);

Troubleshooting

Container element with ID '...' not found Make sure the target <div> exists in the DOM before calling init(). If you are using a framework, call init() after the component mounts (e.g., inside useEffect or mounted()).

Invalid API credentials Double-check that apiKey and apiSecret match the values shown in your MyGigsters dashboard. The secret is shown only once — if lost, generate a new one.

Airwallex form doesn't load / Failed to get Airwallex authorization Ensure your page is served over HTTPS. crypto.subtle is unavailable on plain HTTP (except localhost). Also verify your account has Airwallex integration enabled.

window.crypto.subtle is undefined You are either on HTTP (not HTTPS) or using a very old browser. See Requirements.

Styles look wrong / modal appears behind other elements The modal is mounted on <body> with z-index: 2147483647. If another element on your page has a higher stacking context, adjust accordingly. Because the SDK uses Shadow DOM, your global CSS reset will not affect it.

Dark mode isn't applying to the Airwallex iframe Airwallex theme support depends on your Airwallex account configuration. The SDK passes theme: { mode: 'dark' } during initialization, but the Airwallex iframe may override it.

Changelog

1.0.0

• Initial public release
• Indian entity flow with real-time IFSC verification
• Australia / global entity flow via Airwallex PKCE integration
• Shadow DOM isolation
• Light / dark theming with runtime setTheme() support
• ESM, CJS, and UMD builds
• Auto-init via data-mygigsters-config script attribute

License

MIT © MyGigsters