Connect Widget

O Connect Widget é o frontend hospedado da Malvo que cuida de toda a jornada de conexão de uma instituição financeira: seleção do banco, validação de credenciais, autenticação multifator (MFA), redirect OAuth do Open Finance, tratamento de erros e os casos específicos de cada instituição. Você não precisa construir essa UI banco a banco. O contrato é simples: seu backend gera um connectToken de 30 minutos e o widget produz um Item — a representação de uma conexão entre um usuário e uma instituição. A partir daí, todos os dados são lidos no servidor com a sua X-API-KEY.

A Malvo faz apenas agregação de dados. O Connect Widget conduz somente consentimentos de recepção de dados (Items) — não há iniciação de pagamentos (ITP), Pix ou boletos.

Plataformas suportadas

O widget é a mesma aplicação hospedada em https://malvo.io/connect, embrulhada por SDKs nativos de cada plataforma. Veja a visão geral dos SDKs para instalação e exemplos completos.

Web / Script tag

Bundle versionado que expõe o global window.MalvoConnect. Sem build, basta uma <script>.

React / Next.js

Pacote @malvo/react-connect — o componente monta o widget ao renderizar.

React Native

Pacote @malvo/react-native-connect para apps iOS e Android com React Native.

Flutter

Pacote flutter_malvo_connect para apps Flutter.

Modelo de segurança

As credenciais ficam na infraestrutura da Malvo

O usuário digita as credenciais (ou autoriza via OAuth) na UI hospedada da Malvo, nunca na sua aplicação. Você nunca vê nem armazena senhas de banco.

O connectToken não lê dados

O connectToken só dirige o widget. Ele não consegue ler dados de produto (contas, transações etc.): qualquer tentativa de usá-lo nessas rotas retorna 403 Forbidden. Dados são lidos apenas server-side com X-API-KEY.

Os webhooks são a fonte da verdade

Os callbacks do frontend são best-effort — o usuário pode fechar a aba antes do onSuccess disparar. O sinal autoritativo de que um Item está pronto são os webhooks item/created / item/updated no seu backend. Veja Webhooks.

Pré-requisito no backend

Toda integração precisa de um endpoint autenticado no seu backend que devolva um connectToken recém-gerado. A cadeia é: POST /auth (com clientId + clientSecret) → apiKey (TTL de 2h) → POST /connect_token → accessToken (TTL de 30 min).

Nunca exponha clientId, clientSecret ou apiKey no frontend. O connectToken é o único segredo que pode chegar ao cliente — e ele já é limitado a 30 minutos e a um único fluxo de Item.

// 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 recebe esse accessToken e o passa ao widget. Gere um token novo a cada montagem do widget.

Parâmetros de inicialização

As opções abaixo formam o contrato comum do script tag, React, React Native e Flutter. Cada SDK também documenta opções específicas de plataforma, como oauthRedirectUri no mobile.

Obrigatório

Opção	Tipo	Descrição
`connectToken`	string	O token de 30 minutos do `POST /connect_token`. Única opção obrigatória.

Filtragem e seleção

Opção	Tipo	Descrição
`connectorTypes`	string[]	Restringe a lista por tipo, ex. `['PERSONAL_BANK']`, `['BUSINESS_BANK']`.
`connectorIds`	number[]	Mostra apenas estes IDs de conector.
`countries`	string[]	Códigos ISO-3166-1 alpha-2, ex. `['BR']` ou `['FI', 'SE', 'GB']`.
`selectedConnectorId`	number	Pula o seletor de instituições e vai direto para a tela de login do conector.
`includeSandbox`	boolean	Mostra conectores de sandbox (só desenvolvimento; padrão `false`).

UX

Opção	Tipo	Descrição
`language`	`'pt'` \| `'en'`	Idioma do fluxo hospedado; padrão `pt`.

Modo de atualização

Opção	Tipo	Descrição
`updateItem`	string (itemId)	Conduz a atualização de um Item existente. O `connectToken` precisa ter sido gerado com o mesmo `itemId`. Veja Modo de atualização.

No widget hospedado/JavaScript e no componente React web, oauthRedirectUri não é uma opção local: ele é configurado server-side no objeto options do POST /connect_token (ou no POST /items). Os SDKs React Native, Expo e Flutter também recebem o mesmo URI completo como prop local para validar a retomada pelo navegador do sistema. O backend inclui um malvoFlowId reservado e os SDKs só retomam quando ele corresponde ao Connect Token atual. Veja OAuth.

Callbacks

Callback	Assinatura	Dispara quando
`onSuccess`	`(itemData) => void`, onde `itemData = { item: { id, status, connector, ... } }`	A conexão (ou atualização) teve sucesso. `item` traz no mínimo `id` (UUID), `status` e `connector`.
`onError`	`(error) => void`, onde `error = { code, message, itemId? }`	A conexão falhou. `code` inclui os códigos de erro de Item (`INVALID_CREDENTIALS`, `INVALID_CREDENTIALS_MFA`, `ALREADY_LOGGED_IN`, `ACCOUNT_LOCKED`, `ACCOUNT_NEEDS_ACTION`, `SITE_NOT_AVAILABLE`, `USER_AUTHORIZATION_PENDING`, `USER_NOT_SUPPORTED`, `CONNECTOR_DISABLED`, `CONNECTION_ERROR`) e os códigos do widget `UNAUTHORIZED` e `TOKEN_EXPIRED`.
`onOpen`	`() => void`	O widget foi exibido.
`onClose`	`() => void`	O widget foi fechado — dispara tanto em sucesso quanto em abandono pelo usuário.
`onEvent`	`(event) => void`	Telemetria fina de cada passo (abaixo).

Quando o onError retorna TOKEN_EXPIRED ou UNAUTHORIZED, gere um novo connectToken (POST /connect_token) e reabra o widget. Os demais códigos seguem a tabela de erros de Item da documentação de webhooks.

Eventos do `onEvent`

onEvent recebe o evento OPEN emitido pelo wrapper e as mensagens autenticadas do widget: malvo:success, malvo:error e malvo:close. Os payloads são os mesmos dos callbacks correspondentes. Não use telemetria de frontend como fonte de persistência; webhooks continuam sendo o contrato autoritativo.

Os callbacks são apenas ganchos de UX. O sinal autoritativo de que um Item está pronto é o webhook item/created / item/updated no seu backend — o usuário pode fechar a aba antes do onSuccess rodar.

Diagrama de sequência

Backend do cliente            API da Malvo                 Widget (navegador)          Banco (via Open Finance)
     |  POST /auth                  |                              |                          |
     |----------------------------->|                              |                          |
     |  { apiKey } (TTL 2h)         |                              |                          |
     |  POST /connect_token         |                              |                          |
     |  { itemId?, options }        |                              |                          |
     |----------------------------->|                              |                          |
     |  { accessToken } (TTL 30min) |                              |                          |
     |  --- token para o frontend ------------------------------>  |                          |
     |                              |   init() / mount             |                          |
     |                              |<---- onOpen ----------------  |                          |
     |                              |   usuário escolhe a instituição                         |
     |                              |   consentimento + login / redirect OAuth ------------->  |
     |                              |<------- redirect de volta ao oauthRedirectUri --------- |
     |                              |   Item criado, sync inicia   |                          |
     |   webhook item/created       |                              |                          |
     |<-----------------------------|                              |                          |
     |                              |  onSuccess({ item }) -------> frontend do cliente       |
     |   webhook item/updated (sync concluído)                     |                          |
     |<-----------------------------|                              |                          |
     |   GET /items/{id}, /accounts, /transactions  (X-API-KEY)    |                          |
     |----------------------------->|                              |                          |

Invariantes:

A leitura de dados de produto é sempre server-side com X-API-KEY; o connectToken recebe 403 nessas rotas.
O cliente trata onSuccess apenas como sinal de UX; a persistência é dirigida pelos webhooks item/created → item/updated.
Um Item novo busca até 365 dias no Brasil ou o maior histórico disponível no Open Banking internacional; as atualizações seguintes são incrementais.

Próximos passos

Modo de atualização

Reconecte Items em LOGIN_ERROR, WAITING_USER_INPUT ou OUTDATED.

OAuth do Open Finance e Open Banking

Configure o oauthRedirectUri e o redirect por plataforma.

Customização

Marca, cores e conectores via Dashboard.

SDKs

Instalação e exemplos por plataforma.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Connect Widget

Plataformas suportadas

Web / Script tag

React / Next.js

React Native

Flutter

Modelo de segurança

Pré-requisito no backend

Parâmetros de inicialização

Obrigatório

Filtragem e seleção

UX

Modo de atualização

Callbacks

Eventos do `onEvent`

Diagrama de sequência

Próximos passos

Modo de atualização

OAuth do Open Finance e Open Banking

Customização

SDKs

​Plataformas suportadas

Web / Script tag

React / Next.js

React Native

Flutter

​Modelo de segurança

​Pré-requisito no backend

​Parâmetros de inicialização

​Obrigatório

​Filtragem e seleção

​UX

​Modo de atualização

​Callbacks

​Eventos do onEvent

​Diagrama de sequência

​Próximos passos

Modo de atualização

OAuth do Open Finance e Open Banking

Customização

SDKs

Plataformas suportadas

Modelo de segurança

Pré-requisito no backend

Parâmetros de inicialização

Obrigatório

Filtragem e seleção

UX

Modo de atualização

Callbacks

Eventos do `onEvent`

Diagrama de sequência

Próximos passos