Conectar um banco

Este guia mostra o caminho completo de uma conexão bancária na Malvo: o seu backend gera um connectToken, o frontend abre o Connect Widget, o usuário autoriza no banco e — quando o webhook item/created chega — você lê os dados com o X-API-KEY no servidor.

Há um único host de API: https://api.malvo.io. O widget é servido em https://malvo.io. O clientId, o clientSecret e o apiKey vivem apenas no backend; o navegador só recebe o connectToken (válido por 30 minutos).

Visão geral do fluxo

O backend gera um connectToken

Troque suas credenciais por um apiKey (POST /auth, válido por 2 horas) e o apiKey por um connectToken (POST /connect_token, válido por 30 minutos). Os dois passos rodam no servidor.

O frontend abre o Connect Widget

Com o connectToken, abra o widget (React com @malvo/react-connect ou via script global). O usuário escolhe a instituição e autoriza.

O usuário autoriza no banco

Em conectores Open Finance/Open Banking, o usuário é redirecionado para a autorização do banco e volta depois para o seu oauthRedirectUri. No Brasil, o conector normalmente pede CPF/CNPJ; no fluxo internacional, normalmente não há entrada antes do redirect, mas alguns ASPSPs podem anunciar uma seleção de método de autenticação.

O webhook item/created chega

Quando a conexão é concluída, a Malvo envia item/created para o seu webhookUrl. Esse é o sinal autoritativo de que o Item existe.

Você lê os dados no servidor

Com o itemId, leia GET /items/{id} e GET /accounts?itemId=... usando o X-API-KEY.

Os webhooks são a fonte da verdade. O callback onSuccess do widget é best-effort — o usuário pode fechar a aba antes de ele disparar. Nunca dispare lógica de negócio crítica no onSuccess; aja sobre item/created / item/updated.

1. Gere o connectToken no backend

Exponha um endpoint autenticado no seu backend (ex.: POST /api/malvo/connect-token) que devolve um accessToken novo a cada chamada. Ele faz a cadeia POST /auth → apiKey → POST /connect_token → accessToken.

Node (fetch)

// POST /api/malvo/connect-token  (no seu backend)
export async function createConnectToken(req, res) {
  // 1. credenciais → apiKey (2h)
  const authRes = 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,
    }),
  });
  const { apiKey } = await authRes.json();

  // 2. apiKey → connectToken (30 min)
  const tokenRes = 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, // ex.: "maria-silva-42"
        webhookUrl: "https://seuapp.com.br/webhooks/malvo",
        oauthRedirectUri: "https://seuapp.com.br/oauth/callback",
        products: ["ACCOUNTS", "TRANSACTIONS"],
      },
    }),
  });
  const { accessToken } = await tokenRes.json();

  // devolva apenas o accessToken ao frontend
  return res.json({ accessToken });
}

Faça cache do apiKey (renove antes de 1h50). Em um 403 no /connect_token, refaça o POST /auth e tente de novo — nesse endpoint, falha de autenticação aparece como 403, não 401. Gere um connectToken novo a cada vez que o usuário abrir o widget.

O clientUserId correlaciona os webhooks de volta ao seu usuário sem consulta ao banco de dados — ele é ecoado em cada payload de webhook. Passe o accessToken ao frontend e abra o widget. Você pode usar o componente React ou o script global.

React (@malvo/react-connect)
Script global (widget.js)
URL hospedada

npm install @malvo/react-connect

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

export function ConnectBank({ token }: { token: string }) {
  return (
    <MalvoConnect
      connectToken={token}
      onSuccess={({ item }) => console.log("Item criado:", item.id)}
      onError={(err) => console.error(err)}
      onClose={() => console.log("widget fechado")}
    />
  );
}

O componente monta o widget assim que é renderizado; desmontar fecha o widget.

<script src="https://malvo.io/widget.js"></script>
<script>
  const malvoConnect = MalvoConnect.init({
    connectToken: "<accessToken do backend>",
    onSuccess: (itemData) => {
      // itemData.item.id, itemData.item.status, itemData.item.connector
      console.log("Item criado:", itemData.item.id);
    },
    onError: (error) => console.error("Erro no Connect:", error),
    onClose: () => console.log("widget fechado"),
  });

  // init() já abriu o popup; use malvoConnect.close() para fechá-lo.
</script>

Se preferir não embutir o script, redirecione o usuário para o widget hospedado, passando o token na query:

https://malvo.io/connect?token=<accessToken do backend>

Ao concluir, o usuário volta para o seu oauthRedirectUri. A persistência continua sendo dirigida pelos webhooks.

Se o onError retornar TOKEN_EXPIRED ou UNAUTHORIZED, gere um novo connectToken (POST /connect_token) e reabra o widget. Os demais códigos de erro de Item são tratados no fluxo de atualização (veja Tratar MFA).

3. O caminho regulado (dados do conector → redirect)

Em conectores regulados, o usuário não digita senha na sua aplicação. No Brasil, informa CPF ou CNPJ conforme connector.credentials; no fluxo internacional, não há senha ou token bancário antes do redirect. Alguns ASPSPs podem declarar o select authMethod; nesse caso, envie apenas um value anunciado em connector.credentials[].options. Depois de autorizar, a Malvo conclui o callback do provedor e devolve o usuário ao oauthRedirectUri configurado no connect_token.

connect_token com oauthRedirectUri

await fetch("https://api.malvo.io/connect_token", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-KEY": apiKey },
  body: JSON.stringify({
    options: {
      clientUserId: "maria-silva-42",
      oauthRedirectUri: "https://seuapp.com.br/oauth/callback",
      webhookUrl: "https://seuapp.com.br/webhooks/malvo",
    },
  }),
});

Os campos brasileiros de CPF/CNPJ são exibidos a partir de connector.credentials; o widget não aceita pré-preenchimento de documento. No fluxo internacional, selecione o catálogo por countries, connectorIds e connectorTypes. Quando necessário, o próprio widget renderiza authMethod; as credenciais bancárias são coletadas depois pela interface de autorização:

<MalvoConnect
  connectToken={token}
  countries={["GB"]}
  connectorTypes={["PERSONAL_BANK"]}
  onSuccess={({ item }) => console.log(item.id)}
/>

MalvoConnect.init({
  connectToken: token,
  countries: ["GB"],
  connectorTypes: ["PERSONAL_BANK"],
  onSuccess: (itemData) => console.log(itemData.item.id),
});

O oauthRedirectUri deve ser HTTPS ou um deep link (ex.: myapp://oauth/callback). URLs http:// e localhost são rejeitadas. O link de login do Open Finance é de uso único — entregue-o por navegador in-app ou copiar/colar, nunca por apps de mensagem que pré-carregam links.

A cobertura internacional é dinâmica. A Malvo pode ser configurada para 31 países, mas publica somente os ASPSPs AIS ativos para a configuração contratada. Liste GET /connectors em runtime; não hardcode bancos ou IDs.

4. Receba o webhook item/created

Quando a conexão termina, a Malvo envia item/created para o seu webhookUrl. Responda 2XX em até 5 segundos e processe de forma assíncrona.

Webhook item/created

{
  "event": "item/created",
  "eventId": "d876fd7c-e9bd-4c4c-bd46-cc96c62aac29",
  "itemId": "a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a",
  "triggeredBy": "USER",
  "clientUserId": "maria-silva-42"
}

Handler do webhook (Node)

app.post("/webhooks/malvo", async (req, res) => {
  // responda rápido; processe depois
  res.sendStatus(200);

  const { event, eventId, itemId } = req.body;

  // dedupe pelo eventId (mesmo eventId é reusado em redeliveries)
  if (await alreadyProcessed(eventId)) return;

  if (event === "item/created" || event === "item/updated") {
    await readItemData(itemId);
  }
});

O eventId é a chave de idempotência: persista-o e trate entregas repetidas como no-op. No Brasil, a coleta inicial busca até 365 dias; no fluxo internacional ela usa a maior janela que o ASPSP disponibiliza. Ao concluir, chega item/updated.

5. Leia os dados no servidor

Com o itemId, leia o Item e suas contas usando o X-API-KEY (sempre server-side — o connectToken recebe 403 nessas rotas).

curl "https://api.malvo.io/items/a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a" \
  -H "X-API-KEY: $MALVO_API_KEY"

curl "https://api.malvo.io/accounts?itemId=a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a" \
  -H "X-API-KEY: $MALVO_API_KEY"

async function readItemData(itemId) {
  const headers = { "X-API-KEY": process.env.MALVO_API_KEY };

  const item = await fetch(`https://api.malvo.io/items/${itemId}`, { headers })
    .then((r) => r.json());

  const { results: accounts } = await fetch(
    `https://api.malvo.io/accounts?itemId=${itemId}`,
    { headers },
  ).then((r) => r.json());

  // para cada conta, leia as transações em /v2/transactions?accountId=...
  return { item, accounts };
}

A resposta de GET /accounts traz bankData (contas) ou creditData (cartões) em cada conta. Para ler as transações de cada conta, use accountId em /v2/transactions.

Próximos passos

Sincronizar transações

Pagine /v2/transactions por cursor e mantenha as transações em dia via webhooks.

Tratar MFA

Resolva WAITING_USER_INPUT enviando o token ou abrindo o widget em update mode.

Connect Widget

Todas as opções, callbacks e o fluxo OAuth do Open Finance.

Webhooks

Os payloads exatos de cada evento do ciclo de vida do Item.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Conectar um banco

Visão geral do fluxo

1. Gere o connectToken no backend

2. Abra o Connect Widget no frontend

3. O caminho regulado (dados do conector → redirect)

4. Receba o webhook item/created

5. Leia os dados no servidor

Próximos passos

Sincronizar transações

Tratar MFA

Connect Widget

Webhooks

​Visão geral do fluxo

​1. Gere o connectToken no backend

​2. Abra o Connect Widget no frontend

​3. O caminho regulado (dados do conector → redirect)

​4. Receba o webhook item/created

​5. Leia os dados no servidor

​Próximos passos

Sincronizar transações

Tratar MFA

Connect Widget

Webhooks

Visão geral do fluxo

1. Gere o connectToken no backend

2. Abra o Connect Widget no frontend

3. O caminho regulado (dados do conector → redirect)

4. Receba o webhook item/created

5. Leia os dados no servidor

Próximos passos