@malvo/react-connect

React component for the hosted Malvo Connect widget (Open Finance Brasil), talking to your own Malvo API.

It renders the hosted widget ({baseUrl}/connect?token=...) in an iframe modal and bridges its postMessage events to your callbacks.

Install

npm install @malvo/react-connect

Usage

The only required input is a Connect Token minted by your backend (POST /auth → apiKey → POST /connect_token → accessToken, 30-min TTL). Never ship your clientId/clientSecret to the browser.

import { useState } from "react";
import { MalvoConnect } from "@malvo/react-connect";

export function ConnectBankButton({ token }: { token: string }) {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button onClick={() => setOpen(true)}>Conectar banco</button>
      {open && (
        <MalvoConnect
          connectToken={token}
          baseUrl="https://malvo.io"
          includeSandbox={process.env.NODE_ENV !== "production"}
          onSuccess={({ item }) => console.log("item", item.id)}
          onError={(err) => console.error(err.code, err.message)}
          onClose={() => setOpen(false)}
          onEvent={(e) => console.debug("event", e.type)}
        />
      )}
    </>
  );
}

Mounting opens the widget; unmounting closes it. All options are accepted as props.

Webhooks are the source of truth. onSuccess is best-effort UX — the user may close the tab first. Persist connections from the item/created / item/updated webhooks on your backend.

Open Finance / OAuth

Banks reject iframe framing, so when an Open Finance connector is selected the widget authorizes in a top-level popup and resumes automatically when it returns. No extra setup is required; just don't block popups for your origin.

Props

| Prop | Type | Notes | |---|---|---| | connectToken | string | Required. | | baseUrl | string | malvo-web origin. Default https://malvo.io. | | includeSandbox | boolean | Show sandbox connectors. | | updateItem | string | Item id for an update flow. | | connectorTypes / connectorIds / countries / language / selectedConnectorId | — | Filtering / UX hints. | | onSuccess / onError / onOpen / onClose / onEvent | callbacks | Widget lifecycle callbacks. |