React / Next.js

O pacote @malvo/react-connect é o componente React para o Connect Widget hospedado da Malvo (Open Finance Brasil e Open Banking internacional). Ele renderiza o widget hospedado ({baseUrl}/connect?token=...) em um iframe modal e converte os eventos postMessage do widget nos seus callbacks.

Instalação

npm install @malvo/react-connect

Uso

A única entrada obrigatória é um connectToken gerado pelo seu backend. Nunca envie clientId/clientSecret ao navegador — veja o snippet do backend.

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)}
        />
      )}
    </>
  );
}

Montar abre o widget; desmontar o fecha. No exemplo acima, o botão alterna open: ao ficar true, o <MalvoConnect> é montado e o widget abre; quando o onClose dispara, voltamos open para false e o componente é desmontado, fechando o widget. Todas as opções são aceitas como props. A bridge é vinculada nos dois sentidos: o componente transmite automaticamente a origem exata do integrador para o widget, que a usa como targetOrigin; na volta, o SDK aceita a mensagem somente quando origem e contentWindow correspondem ao iframe criado por ele. Em páginas SSR/Next.js, o iframe só navega depois da hidratação e da instalação do listener. Se connectToken ou os filtros mudarem, o componente cria outro iframe e separa o novo fluxo de qualquer mensagem tardia do anterior.

Os webhooks são a fonte da verdade. O onSuccess é apenas UX best-effort — o usuário pode fechar a aba antes dele disparar. Persista as conexões a partir dos webhooks item/created / item/updated no seu backend. Veja Webhooks.

Os bancos rejeitam ser exibidos em iframe, então, quando um conector de Open Finance é escolhido, o widget autoriza em um popup top-level e retoma o fluxo automaticamente ao retornar. Não é preciso configuração extra — apenas não bloqueie popups para a sua origem.

Props

Todas as props de MalvoConnectOptions:

string

required

O connectToken de 30 minutos gerado pelo seu backend (POST /connect_token). Única prop obrigatória.

string

default:"https://malvo.io"

Origem que serve o widget hospedado.

boolean

Mostra conectores de sandbox (apenas em desenvolvimento).

string

Id de um Item existente, para conduzir um fluxo de atualização. O connectToken precisa ter sido gerado com esse mesmo itemId. Veja Modo de atualização.

string[]

Restringe a lista de instituições por tipo (ex.: ["PERSONAL_BANK"]).

number[]

Mostra apenas estes IDs de conector.

string[]

Códigos ISO-3166-1 alpha-2 (ex.: ["BR"]).

'pt' | 'en'

Idioma do fluxo hospedado. Padrão pt.

number

Pula o seletor de instituições e vai direto para a tela de login desse conector.

(data: { item }) => void

A conexão (ou atualização) teve sucesso. data.item traz no mínimo id, e pode incluir status e connector.

(error: { code, message, itemId? }) => void

A conexão falhou. code inclui os códigos de erro de Item (INVALID_CREDENTIALS, ACCOUNT_LOCKED, SITE_NOT_AVAILABLE, …) e os códigos do widget UNAUTHORIZED e TOKEN_EXPIRED. Em TOKEN_EXPIRED/UNAUTHORIZED, gere um token novo e remonte o componente.

() => void

O widget terminou o primeiro carregamento e está visível.

() => void

O widget foi fechado (abandono pelo usuário, sucesso ou erro).

(event: { type, ... }) => void

Recebe OPEN uma vez e as mensagens confiáveis malvo:success, malvo:error e malvo:close sem alteração. O retorno OAuth interno não faz parte dessa telemetria.

Tipos

Tipo	Forma
`MalvoSuccess`	`{ item: { id: string; status?: string; ... } }`
`MalvoError`	`{ code: string; message: string; itemId?: string }`
`MalvoEvent`	`{ type: string; [key: string]: unknown }`

Gerando o connectToken no backend

O componente só recebe o connectToken. Gere-o em um endpoint autenticado do seu backend — nunca no navegador.

// POST /api/malvo/connect-token  (backend do cliente)
const { apiKey } = await fetch("https://api.malvo.io/auth", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: process.env.MALVO_CLIENT_ID,
    clientSecret: process.env.MALVO_CLIENT_SECRET,
  }),
}).then((r) => r.json());

const { accessToken } = await fetch("https://api.malvo.io/connect_token", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-KEY": apiKey },
  body: JSON.stringify({
    options: {
      clientUserId: req.user.id,
      webhookUrl: process.env.MALVO_WEBHOOK_URL,
    },
  }),
}).then((r) => r.json());

return { accessToken }; // o frontend passa isto como connectToken

Veja o uso completo server-side em Node (server).

Próximos passos

Connect Widget

Todas as opções, callbacks e o diagrama de sequência.

Node (server)

Helper de auth, geração do connectToken e leitura de dados.

Web (script tag)

A versão vanilla, sem build, via https://malvo.io/widget.js.

Webhooks

A fonte da verdade para o ciclo de vida dos Items.

Visão geral

Web & JavaScript

Mobile

React / Next.js

Instalação

Uso

Props

Tipos

Gerando o connectToken no backend

Próximos passos

Connect Widget

Node (server)

Web (script tag)

Webhooks

​Instalação

​Uso

​Open Finance / OAuth em popup

​Props

​Tipos

​Gerando o connectToken no backend

​Próximos passos

Connect Widget

Node (server)

Web (script tag)

Webhooks

Instalação

Uso

Open Finance / OAuth em popup

Props

Tipos

Gerando o connectToken no backend

Próximos passos