Integration contract

Canonical inputs, outputs, sequence, and trust boundaries for Connect.js 2.2.0.

This page is the compact integration contract for humans and coding agents. It describes the verified behavior of @mono.co/connect.js 2.2.0.

Account-linking sequence

Browser                                          Backend
-------                                          -------
new Connect({ public key, auth scope, ... })
setup()
open()
user completes the hosted flow
onSuccess({ code })
                 ─── POST { code } ────────────→ authenticated route
                                                  POST /v2/accounts/auth
                                                  header: mono-sec-key
                                                  store returned account ID
                 ←── application response ──────

Invariants

Browser lifecycle

• key is required when constructing Connect.
• onSuccess is required when constructing Connect.
• Account linking should set scope: "auth" and provide data.customer.
• Call setup() before open() for new account linking and payment flows.
• Call reauthorise(accountId) before open() for reauthorization.

Trust boundaries and outputs

• reauthorise() accepts an account ID string, not an auth code or reauth token.
• The public key may be used in browser code.
• The secret key must remain on the backend.
• An account-linking onSuccess result contains a short-lived code; the backend exchanges it for an account ID.
• Event payloads vary by event and should be read defensively.

Constructor contract

new Connect({
  key,        // required string
  onSuccess,  // required function
  onClose,    // optional function
  onLoad,     // optional function
  onEvent,    // optional function
  ...config   // forwarded to the hosted widget
})

Missing required values throw synchronously:

PUBLIC_KEY is required
onSuccess callback is required

Method contract

Method	Input	Effect	Return value
setup(config?)	Optional setup object	Mounts a hidden widget for the configured flow.	No documented value
reauthorise(accountId)	Required account ID string	Mounts a hidden reauthorization widget.	No documented value
open()	None	Shows the mounted widget and begins listening for widget messages.	No documented value
close()	None	Hides the widget, removes the active message listener, and calls onClose.	No documented value
fetchInstitutions()	None	Requests current coverage data from https://api.withmono.com/coverage.	Axios promise

Flow outputs

Flow	Browser success output	Required server action
Account linking	{ code }	Exchange code for account ID with the secret key.
Reauthorization	Success data from the reauth widget	Complete the current Mono server-side reauthorization flow.
Payment	Charge data from the payment widget	Verify the payment server-side before fulfillment.

Source boundary

This contract covers the browser SDK implementation. Mono’s official API documentation remains authoritative for server endpoint schemas, payment product behavior, data access, authentication policy, and production requirements.