> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mygigsters.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Embed the Beneficiary SDK

> Collect worker bank details with a hosted form.

The MyGigsters Beneficiary SDK lets you embed a fully-featured beneficiary onboarding form directly into any website. Workers can securely submit their bank details through a pre-built, styled UI — no backend integration required on your side.

## Installation

Choose the method that best fits your project — load via a `<script>` tag for plain HTML sites, or install via **npm** for React, Vue, Angular, or any bundler-based app.

Add the SDK script tag to your HTML page. No build step required.

```html theme={null}
<!-- Load SDK -->
<script src="https://qa-payments.mygigsters.com.au/beneficiary-sdk-entry.js"></script>
```

### Full HTML Example

```html theme={null}
<!DOCTYPE html>
<html>
<body>
  <!-- Container for the form -->
  <div id="beneficiary-form"></div>

  <!-- Load SDK -->
  <script src="https://qa-payments.mygigsters.com.au/beneficiary-sdk-entry.js"></script>

  <!-- Initialize -->
  <script>
    MygigstersBeneficiary.init({
      apiKey: "your_api_key",
      apiSecret: "your_secret_key",
      env: "demo",              // "demo" or "prod"
      containerId: "beneficiary-form",
      mode: "light",            // "light" or "dark"
      onSuccess: (data) => console.log("Success:", data),
      onError: (err) => console.error("Error:", err),
      onClose: () => console.log("Closed")
    });
  </script>
</body>
</html>
```

### Auto-Initialize via Script Attribute

You can pass configuration directly on the `<script>` tag — no extra JavaScript needed (callbacks not available with this method):

```html theme={null}
<div id="beneficiary-form"></div>

<script
  src="https://qa-payments.mygigsters.com.au/beneficiary-sdk-entry.js"
  data-mygigsters-config='{
    "apiKey":      "your_api_key",
    "apiSecret":   "your_secret_key",
    "env":         "demo",
    "containerId": "beneficiary-form",
    "mode":        "light"
  }'
></script>
```

## How It Works

### 1. Add the SDK to Your Project

Either include the `<script>` tag for CDN usage (exposes `window.MygigstersBeneficiary`), or install via `npm install @mygigsters/beneficiary-sdk` and import `MygigstersBeneficiarySDK` in your code.

### 2. Create a Container Element

Add an empty `<div>` with a unique `id` (e.g. `<div id="beneficiary-form"></div>`). The SDK will mount its UI inside this element using Shadow DOM for full style isolation.

### 3. Initialize with Credentials

Call `.init(config)` with your API key and secret. The SDK authenticates against the MyGigsters backend, then renders the beneficiary form inside the container.

### 4. Handle Callbacks

Use the `onSuccess`, `onError`, and `onClose` callbacks to react to form events in your application — for example, displaying a confirmation message or redirecting the user.

## Configuration Options

Pass these options to `init()`:

| Parameter | Type | Description |
| - | - | - |
| `apiKey` (required) | string | Your UUID-style API key generated from the MyGigsters dashboard (API Keys section). |
| `apiSecret` (required) | string | The one-time secret / random password shown when the API key was created. |
| `containerId` (required) | string | The `id` of the DOM element where the form will be mounted (e.g. `"beneficiary-form"`). |
| `env` (optional) | string | Environment to connect to. Use `"demo"` for testing (QA) or `"prod"` for live. Defaults to `"prod"`. |
| `mode` (optional) | string | UI theme — `"light"` or `"dark"`. Defaults to `"light"`. |
| `talentId` (optional) | string | Optional talent / worker ID to associate the beneficiary with a specific worker in your system. |
| `onSuccess` (optional) | function | Callback fired when the beneficiary is saved successfully. Receives the result data object as an argument. |
| `onError` (optional) | function | Callback fired when an error occurs. Receives the error object as an argument. |
| `onClose` (optional) | function | Callback fired when the user closes the form. |

## SDK Methods

After initialization, you can control the form programmatically:

| Method | Returns | Description |
| - | - | - |
| `init(config)` | Promise | Initialize and render the beneficiary form. Authenticates with the backend and mounts the UI into the specified container. |
| `show()` | void | Show the beneficiary form if it has been hidden. |
| `hide()` | void | Hide the beneficiary form without destroying it. Form state is preserved. |
| `destroy()` | void | Completely remove the form from the DOM and clean up all resources. Call this when navigating away or unmounting. |
| `setTheme(mode)` | void | Switch the UI theme at runtime. Pass `"light"` or `"dark"`. |
| `getInstance()` (CDN only) | object | Returns the underlying SDK instance for advanced use (only available when using the CDN/script tag approach). |

## Important Notes

> [!NOTE]
>
> **CDN vs npm — Global Name Difference:** When using the **CDN / script tag**, the global object is `MygigstersBeneficiary`. When using the **npm package**, import the named export `MygigstersBeneficiarySDK`. The API methods are identical for both.

## Environment URLs

| Environment | SDK script URL and `env` value | Use for |
| - | - | - |
| Demo (QA) | Script: `https://qa-payments.mygigsters.com.au/beneficiary-sdk-entry.js`, env: `"demo"` | For testing and development. |
| Production | Script: `https://prod-payments.mygigsters.com.au/beneficiary-sdk-entry.js`, env: `"prod"` | For live / production usage. |

## Error Handling

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

```javascript theme={null}
try {
  const sdk = new MygigstersBeneficiarySDK();
  await sdk.init({
    apiKey: 'your_api_key',
    apiSecret: 'your_api_secret',
    env: 'demo',
    containerId: 'beneficiary-form',
  });
} catch (err) {
  // Common errors:
  // "apiKey is required"
  // "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.

## Security & Notes

### Shadow DOM Isolation

The SDK renders inside a closed Shadow DOM, ensuring your page styles never conflict with the form's styles and vice versa.

### Secure Authentication

The SDK uses HTTP Basic Authentication (Base64-encoded `apiKey:apiSecret`) under the hood to obtain a Bearer token. Credentials are never stored in localStorage or sessionStorage — the auth token lives in memory only.

### PKCE Flow for Bank Details

For international (Airwallex) beneficiary forms, the SDK uses a PKCE (Proof Key for Code Exchange) authorization flow with native `crypto.subtle` — no third-party crypto library is used.

### International support

The SDK detects the entity type from your account configuration and renders the appropriate form for the beneficiary's country.

### HTTPS Required

The SDK requires `window.crypto.subtle` which is only available over **HTTPS** (or `localhost` for development). All modern browsers (Chrome 80+, Firefox 78+, Safari 14+, Edge 80+) are supported.

## Troubleshooting

### Container element not found

Make sure the target `<div>` exists in the DOM before calling `init()`. In React, call it inside `useEffect`; in Vue, use `mounted()`.

### Invalid API credentials

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

### Airwallex form doesn't load

Ensure your page is served over **HTTPS**. `crypto.subtle` is unavailable on plain HTTP. Also verify your account has Airwallex integration enabled.

Need your API key? Head to the **Generate API Key** section of the MyGigsters Settings to generate one, then start embedding the Beneficiary Form on your website.

## Quick reference

**Script tag**

```html theme={null}
<!-- 1. Add container -->
<div id="beneficiary-form"></div>

<!-- 2. Load SDK -->
<script src="https://qa-payments.mygigsters.com.au/beneficiary-sdk-entry.js"></script>$2

<!-- 3. Initialize -->
<script>
  MygigstersBeneficiary.init({
    apiKey: "your_api_key",
    apiSecret: "your_secret_key",
    env: "demo",
    containerId: "beneficiary-form",
    mode: "light",
    onSuccess: (data) => console.log("Success:", data),
    onError: (err) => console.error("Error:", err),
    onClose: () => console.log("Closed")
  });
</script>
```

**npm**

```javascript theme={null}
// npm install @mygigsters/beneficiary-sdk$2

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",
  mode:        "light",
  onSuccess: (data) => {
    console.log("Beneficiary added:", data);
  },
  onError: (err) => {
    console.error("Error:", err.message);
  },
  onClose: () => {
    console.log("Modal closed");
  },
});
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.