> ## 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](https://docs.withbenji.com/connect/initialization.md) 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](https://docs.withbenji.com/connect/create_token.md) ([modes](https://docs.withbenji.com/connect/modes.md)).

**onSuccess**

**Arguments**

* **`token`** (`string`) — Short-lived **exchange** token. Use it with [Exchange Token](https://docs.withbenji.com/connect/exchange_token.md) 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"
  }
}
```

### onExit

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

**onExit**

**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.

### onEvent

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

**onEvent**

**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.

### onError

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

**onError**

**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.


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