Benji Connect SDK methods and events

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

Methods

open()

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

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 (modes).

Hide onSuccess

Arguments

token (string) — Short-lived exchange token. Use it with 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):

{
  "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.

Hide 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).

Hide 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).

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

The Benji Connect SDK may refine onError payloads in a future release; treat error, error_id, and metadata as the stable integration surface.

Documentation Index

​Methods

​open()

​ping()

​Events

​onSuccess

​onExit

​onEvent

​onError

Methods

open()

ping()

Events

onSuccess

onExit

onEvent

onError