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