Quickstart

Este guia leva você do nada à primeira conexão bancária. Ao final, você terá um Item conectado (usando o sandbox, sem nenhum banco real) e terá lido contas e transações.

O clientSecret e o apiKey vivem apenas no seu backend. O navegador só pode ver o connectToken (válido por 30 minutos). Nunca envie clientId/clientSecret/apiKey ao cliente.

Pegue suas credenciais no Dashboard

Acesse o Dashboard, crie uma Application e copie o clientId e o clientSecret. Guarde-os como variáveis de ambiente no seu servidor (por exemplo, MALVO_CLIENT_ID e MALVO_CLIENT_SECRET).

Troque as credenciais por um apiKey

No backend, chame POST https://api.malvo.io/auth para obter um apiKey (header X-API-KEY, com validade de 2 horas).

curl -X POST https://api.malvo.io/auth \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "'"$MALVO_CLIENT_ID"'",
    "clientSecret": "'"$MALVO_CLIENT_SECRET"'"
  }'
# → { "apiKey": "eyJhbGciOi..." }

const res = 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 res.json();

Faça cache do apiKey e renove-o de forma proativa (por exemplo, antes de 1h50). Em um 401 nas rotas de dados, refaça o POST /auth uma vez e tente de novo.

Gere um connectToken

Ainda no backend, troque o apiKey por um connectToken (accessToken) — o token de 30 minutos que dirige o widget. Use includeSandbox no widget para testar sem banco real.

curl -X POST https://api.malvo.io/connect_token \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $MALVO_API_KEY" \
  -d '{
    "options": {
      "clientUserId": "maria-silva-42",
      "webhookUrl": "https://seuapp.com.br/webhooks/malvo",
      "products": ["ACCOUNTS", "TRANSACTIONS"]
    }
  }'
# → { "accessToken": "eyJ0eXAiOi..." }

const res = 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",
      webhookUrl: "https://seuapp.com.br/webhooks/malvo",
      products: ["ACCOUNTS", "TRANSACTIONS"],
    },
  }),
});
const { accessToken } = await res.json();
// devolva accessToken ao frontend

Exponha esse passo como um endpoint autenticado no seu backend (ex.: POST /api/malvo/connect-token) que devolve um accessToken novo a cada vez.

Abra o Connect Widget no frontend

Com o accessToken em mãos, abra o widget. Ative includeSandbox para que o conector Malvo Bank Open Finance (sandbox) apareça na lista e você possa testar o fluxo completo.

React (@malvo/react-connect)
Script tag global

npm install @malvo/react-connect

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

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

<script src="https://malvo.io/widget.js"></script>
<script>
  // MalvoConnect.init() abre o widget imediatamente e retorna um handle com .close()
  const handle = MalvoConnect.init({
    connectToken: "<accessToken do backend>",
    onSuccess: (data) => {
      console.log("Item criado:", data.item.id);
    },
    onError: (error) => console.error("Erro no Connect:", error),
    onClose: () => console.log("widget fechado"),
  });
</script>

No sandbox, o conector Malvo Bank Open Finance pede só o CPF e redireciona para um banco fictício. Use as credenciais de teste ([email protected] / P@ssword01) para concluir o consentimento e gerar o Item.

onSuccess é best-effort. Não dispare lógica de negócio crítica nele — o usuário pode fechar a aba antes. Use os webhooks como fonte da verdade.

Receba o webhook e leia os dados

Quando o Item é criado e sincronizado, a Malvo envia os webhooks item/created e, ao concluir a coleta, item/updated para o seu webhookUrl. Esse é o sinal para ler os dados no servidor.

Webhook item/created

{
  "event": "item/created",
  "itemId": "a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a",
  "clientUserId": "maria-silva-42"
}

Com o itemId, leia contas e transações usando o X-API-KEY (sempre server-side):

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

curl "https://api.malvo.io/v2/transactions?accountId=<accountId>" \
  -H "X-API-KEY: $MALVO_API_KEY"

As transações já chegam categorizadas. Prefira sempre GET /v2/transactions (versão cursor-based) para sincronização incremental.

Próximos passos

Connect Widget

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

Webhooks

Configure e valide os eventos que governam o ciclo de vida dos Items.

Sincronizar transações

Paginação por cursor em /v2/transactions e atualizações incrementais.

Referência da API

O playground interativo e o detalhamento de cada endpoint.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

Próximos passos

Connect Widget

Webhooks

Sincronizar transações

Referência da API

​Próximos passos

Connect Widget

Webhooks

Sincronizar transações

Referência da API

Próximos passos