---
name: mono-connect-js
description: Integrate @mono.co/connect.js 2.2.0 for browser-based account linking, reauthorization, and supported payment flows while preserving the client/server security boundary.
license: ISC
compatibility: Requires a browser for the widget, a Mono application, and a backend for secret-key API requests. Verified with @mono.co/connect.js 2.2.0.
metadata:
  author: Samuel Umoren
  version: "1.0"
---

# Mono Connect.js integration

Use this skill to implement or review `@mono.co/connect.js`. The guide was checked against version 2.2.0. If it conflicts with Mono's official API documentation or the current SDK source, use those primary sources.

## Decide the flow

| User goal | Initialize with | Success handling |
| --- | --- | --- |
| Link a new or existing customer account | `connect.setup()` | Send `onSuccess({ code })` to the backend for exchange. |
| Reauthorize a linked account | `connect.reauthorise(accountId)` | Send the returned success data to the backend flow required by Mono. |
| Start a supported payment | `connect.setup()` with `scope: "payments"` | Verify returned charge data on the backend before fulfillment. |

## Account-linking workflow

1. Install `@mono.co/connect.js`.
2. Create one browser-side `Connect` instance with `key`, `scope: "auth"`, `data.customer`, and `onSuccess`.
3. Call `setup()` once after the DOM is available.
4. Call `open()` from an explicit user action.
5. Receive `{ code }` in `onSuccess`.
6. POST the code to an authenticated backend route.
7. On the backend, call `POST https://api.withmono.com/v2/accounts/auth` with `mono-sec-key`.
8. Store the returned Mono account ID against the authenticated application user.

## Canonical browser configuration

```javascript
import Connect from "@mono.co/connect.js"

const connect = new Connect({
  key: "PUBLIC_KEY",
  scope: "auth",
  data: { customer: { id: "CUSTOMER_ID" } },
  onSuccess: ({ code }) => sendCodeToBackend(code),
  onClose: () => handleClose(),
  onEvent: (eventName, data) => recordSafeEvent(eventName, data)
})

connect.setup()
```

## Browser lifecycle

- Require `key` and `onSuccess` in every `new Connect(...)` call.
- Use the Mono public key in browser code.
- Use `setup()` and `reauthorise()` separately. The last one called replaces the mounted widget configuration.
- Call `open()` only after `setup()` or `reauthorise()`.

## Trust boundaries

- Keep `MONO_SECRET_KEY` on the backend. Never expose it through public environment variables or frontend bundles.
- Treat the account-linking auth code as short-lived intermediate data, not an account ID.
- Pass a Mono account ID string to `reauthorise()`. Never pass an auth code or reauth token.
- Verify payment results on the backend before fulfilling an order or granting access.
- Do not log credentials, MFA values, BVNs, account numbers, secret keys, or unreviewed event payloads.

## Framework boundaries

- React: create the instance in `useEffect`, store it in `useRef`, and close it on unmount.
- Angular: create the instance in `ngOnInit` and close it in `ngOnDestroy`.
- Next.js: use a Client Component for Connect.js and a server-only Route Handler for the secret-key exchange.

## Exact validation errors

| Error | Meaning |
| --- | --- |
| `PUBLIC_KEY is required` | Constructor `key` is missing. |
| `onSuccess callback is required` | Constructor `onSuccess` is missing. |
| `Account ID is required for re-authorisation` | `reauthorise()` received no account ID. |
| `Invalid accountId: must be a string` | `reauthorise()` received a non-string value. |

## References

- Documentation index: https://sammydocs.mintlify.app/llms.txt
- Full documentation context: https://sammydocs.mintlify.app/llms-full.txt
- Canonical contract: https://sammydocs.mintlify.app/content/sdk/connect-js/reference/integration-contract
- Official Connect.js source: https://github.com/withmono/connect.js
- Official Mono financial-data docs: https://docs.mono.co/docs/financial-data/overview
- Official token exchange: https://docs.mono.co/api/bank-data/authorisation/exchange-token