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

# Benji Connect SDK methods and events

> Overview of supported methods and events in the Benji Connect SDK

Once initialized, the Benji Connect SDK exposes the methods below. User-driven outcomes are delivered through the callbacks you passed in the [initialization](/connect/initialization) step.

## Methods

### open()

Opens the Benji Connect UI in a modal. Call this after construction, typically from a button click or route handler.

```javascript theme={null}
document.getElementById('connectBtn').addEventListener('click', async (e) => {
  e.preventDefault();
  if (sdk) {
    await sdk.open();
  }
});
```

### ping()

Returns the string `'pong'`. Intended for quick debugging to verify the **Benji Connect SDK** bundle loaded; not required for production flows.

## Events

Callbacks match the `@benji-money/connect-sdk` contract. Types below are exported as `BenjiConnectEventType`, `BenjiConnectExitTrigger`, and related interfaces for TypeScript users.

### onSuccess

Fired when the Connect **flow completes successfully** (transport event `FLOW_SUCCESS`). This is the signal that the user finished link, transfer, or redeem as configured by the [connect token](/connect/create_token) ([modes](/connect/modes)).

<Expandable title="onSuccess" defaultOpen="true">
  **Arguments**

  * **`token`** (`string`) — Short-lived **exchange** token. Use it with [Exchange Token](/connect/exchange_token) to obtain access and refresh tokens for user-scoped APIs. Exchange it promptly (see the Exchange Token page for validity).
  * **`metadata`** — Payload aligned with `BenjiConnectOnSuccessMetadata`:
    * **`context`** — SDK context (`namespace`, `version`).
    * **`action`** (optional) — One of `connect`, `transfer`, `redeem` (`BenjiConnectAuthAction`).
    * **`user_data`** (optional) — Structured user and status:
      * **`user`**: `id`, `first_name`, `last_name`, optional `uuid`
      * **`status`**: `status_id`, `num_of_rewards`, `reward_status`, optional `partner_status_tier_id`
      * **`extra_data`** (optional): e.g. totals, dates
    * **`transaction_data`** (optional) — When applicable: `action`, `amount`, `trigger_event_id`, `trigger_name`

  Example shape (illustrative):

  ```json theme={null}
  {
    "context": { "namespace": "benji-connect-sdk", "version": "1.0.0" },
    "action": "connect",
    "user_data": {
      "user": {
        "id": 12345,
        "first_name": "Test",
        "last_name": "User",
        "uuid": "550e8400-e29b-41d4-a716-446655440000"
      },
      "status": {
        "status_id": "********4156",
        "num_of_rewards": 45000,
        "reward_status": "Mosaic 1"
      }
    },
    "transaction_data": {
      "action": "redeem",
      "amount": 1000,
      "trigger_event_id": "abc-123",
      "trigger_name": "connect"
    }
  }
  ```
</Expandable>

### onExit

Fired when the user leaves the Connect UI (transport event `FLOW_EXIT`). The **Benji Connect SDK** closes the modal after this callback.

<Expandable title="onExit" defaultOpen="true">
  **Arguments**

  * **`metadata`** — `BenjiConnectOnExitMetadata`:
    * **`context`**
    * **`trigger`** — Why the UI closed (`BenjiConnectExitTrigger`):
      * **`ACTION_BUTTON_CLICKED`** — User completed the flow and used the primary dismiss/action control.
      * **`CLOSE_BUTTON_CLICKED`** — User closed via the chrome close control.
      * **`TAPPED_OUT_OF_BOUNDS`** — User dismissed by tapping outside the modal (when supported).
      * **`BACK_TO_MERCHANT_CLICKED`** — Deprecated; may still appear in older flows.
    * **`step`** (optional) — Flow step when exit occurred.

  `onExit` can run whether or not `onSuccess` ran. Only **`onSuccess`** indicates a completed successful Connect flow.
</Expandable>

### onEvent

Fired for mid-flow and auxiliary transport events. The first argument is **`type`** (`BenjiConnectEventType`).

<Expandable title="onEvent" defaultOpen="true">
  **Arguments**

  * **`type`** — Values you may see include:
    * **`AUTH_SUCCESS`** — Mid-flow authentication success. Delivered to **`onEvent`** only (not **`onSuccess`**). Use for progress or analytics; metadata can include action, user, and token-related fields.
    * **`EVENT`** — Generic events with additional fields in **`metadata`**.
    * Other values may be forwarded for forward compatibility.

  * **`metadata`** — Varies by `type`; always includes **`context`**. Additional keys are merged from the payload when present.

  **Routing (important):**

  * **`FLOW_SUCCESS`** invokes **`onSuccess`** with the exchange token — not **`onEvent`**.
  * **`FLOW_EXIT`** invokes **`onExit`** — not **`onEvent`**.
  * **`ERROR`** invokes **`onError`**.

  **Practical distinction:** Implement **`onSuccess`** for “flow completed + exchange token.” Use **`onEvent`** when you need mid-flow **`AUTH_SUCCESS`** or generic **`EVENT`** data before completion.
</Expandable>

### onError

Fired when an error occurs in the Connect flow (`ERROR` transport event).

<Expandable title="onError" defaultOpen="true">
  **Arguments**

  * **`error`** — Typically an `Error` instance or platform-specific error information.
  * **`error_id`** — Identifier for support correlation when applicable.
  * **`metadata`** — Additional context; includes **`context`** where provided.

  Documented error names include:

  * **`unexpected_error`** — Unexpected platform error.
  * **`partner_connect_error`** — Failure while connecting the user to the selected loyalty network.

  <Note>
    The **Benji Connect SDK** may refine **`onError`** payloads in a future release; treat **`error`**, **`error_id`**, and **`metadata`** as the stable integration surface.
  </Note>
</Expandable>