Tratar MFA

Alguns bancos pedem um segundo fator (MFA, OTP ou captcha) durante a conexão. Quando isso acontece, o Item pausa em WAITING_USER_INPUT e a Malvo envia o webhook item/waiting_user_input. Você tem duas formas de resolver: enviar o token via POST /items/{id}/mfa ou reabrir o Connect Widget em update mode para o usuário preencher o que falta.

Há um único host de API: https://api.malvo.io. Toda chamada server-side usa o header X-API-KEY. Os webhooks são a fonte da verdade do estado do Item.

1. Detecte via webhook item/waiting_user_input

Quando o conector exige um desafio, chega este webhook. Ele é o gatilho para você pedir o token ao usuário.

Webhook item/waiting_user_input

{
  "event": "item/waiting_user_input",
  "eventId": "5d2c8e0f-2f64-49a7-a4f2-2d9b4f3f9b77",
  "itemId": "a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a",
  "triggeredBy": "SYNC",
  "clientUserId": "maria-silva-42"
}

2. Leia item.parameter

Com o itemId, leia o Item: o campo parameter descreve exatamente o input esperado (um descritor de credencial), incluindo expiresAt quando o desafio é temporizado. O status do Item será WAITING_USER_INPUT.

GET /items/{id}

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

Trecho do Item (status WAITING_USER_INPUT)

{
  "id": "a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a",
  "status": "WAITING_USER_INPUT",
  "parameter": {
    "name": "token",
    "label": "Código do app",
    "type": "number",
    "placeholder": "123456",
    "validation": "^\\d{6}$",
    "validationMessage": "O código tem 6 dígitos"
  }
}

Use parameter.label, parameter.placeholder e parameter.validation para renderizar o campo certo ao usuário.

POST /items/{id}/mfa
Widget em update mode

Se você coleta o token na sua própria UI, envie-o direto. A execução retoma (LOGIN_MFA_IN_PROGRESS).

cURL

curl -X POST "https://api.malvo.io/items/a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a/mfa" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $MALVO_API_KEY" \
  -d '{ "parameters": { "token": "123456" } }'

Node

await fetch(`https://api.malvo.io/items/${itemId}/mfa`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-KEY": process.env.MALVO_API_KEY,
  },
  body: JSON.stringify({ parameters: { token: "123456" } }),
});

Token errado/expirado → INVALID_CREDENTIALS_MFA.

Se você prefere que o widget conduza, gere um token de atualização (com itemId) e abra o widget em update mode — ele pede apenas o que falta.

Backend: connectToken com itemId

const { accessToken } = await fetch("https://api.malvo.io/connect_token", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-KEY": apiKey },
  body: JSON.stringify({
    itemId: "a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a",
    options: { clientUserId: "maria-silva-42" },
  }),
}).then((r) => r.json());

Frontend: update mode

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

<MalvoConnect
  connectToken={updateToken}
  updateItem="a8f4f3e1-7b2c-4d4e-8f9a-0b1c2d3e4f5a"
  onSuccess={({ item }) => console.log("status:", item.status)}
/>;

Ao concluir, o Item vai para UPDATED e chega o webhook item/updated.

4. Tipos de MFA e impacto no auto-sync

A forma como o desafio aparece muda o fluxo — e se o auto-sync continua disponível:

Tipo	Como aparece	Auto-sync
Sem MFA	Login direto → coleta → `UPDATED`	Habilitado
MFA single-step	O token já vem no formulário inicial (credencial com `mfa: true`); mesmo caminho do sem-MFA	Em geral desabilitado
MFA two-step	Pausa em `WAITING_USER_INPUT`; retoma após `POST /items/{id}/mfa`	Desabilitado

Em single-step, o usuário inclui o token logo no início, então não há pausa em WAITING_USER_INPUT. Em two-step, o Item pausa e você resolve com POST /items/{id}/mfa ou com o widget em update mode. Quando o auto-sync fica desabilitado, atualize sob demanda (acionado pelo usuário), não por polling automático.

5. Teste no sandbox

O sandbox roda no mesmo host e exercita MFA sem banco real. Use o conector Malvo Bank MFA-2 (two-step) para forçar a pausa em WAITING_USER_INPUT.

Campo	Valor de teste
Senha	`password-ok`
Token MFA	`123456`

Crie o Item de teste

Conecte pelo widget com includeSandbox ativo e escolha o conector MFA two-step, ou crie via POST /items com o conector de sandbox apropriado.

Receba item/waiting_user_input

O Item pausa e o webhook chega. Leia item.parameter para saber o campo esperado.

Envie o token de teste

curl -X POST "https://api.malvo.io/items/<itemId>/mfa" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $MALVO_API_KEY" \
  -d '{ "parameters": { "token": "123456" } }'

Confirme o sucesso

Com o token 123456, a coleta segue até UPDATED e chega item/updated. Qualquer token diferente de 123456 → INVALID_CREDENTIALS_MFA.

Próximos passos

Conectar um banco

O fluxo completo de criação do Item, incluindo o caminho Open Finance.

Connect Widget — update mode

Como o widget reautentica, renova consentimento e coleta MFA.

Webhooks

Os payloads de item/waiting_user_input e item/error.

Sandbox

Gatilhos de usuário, fluxos de MFA e credenciais de teste.

Comece aqui

Conceitos

Connect Widget

Webhooks

Guias

Conta & Dashboard

Sandbox & Suporte

1. Detecte via webhook item/waiting_user_input

2. Leia item.parameter

3. Resolva: enviar o token OU abrir o widget

4. Tipos de MFA e impacto no auto-sync

5. Teste no sandbox

Próximos passos

Conectar um banco

Connect Widget — update mode

Webhooks

Sandbox

​1. Detecte via webhook item/waiting_user_input

​2. Leia item.parameter

​3. Resolva: enviar o token OU abrir o widget

​4. Tipos de MFA e impacto no auto-sync

​5. Teste no sandbox

​Próximos passos

Conectar um banco

Connect Widget — update mode

Webhooks

Sandbox

1. Detecte via webhook item/waiting_user_input

2. Leia item.parameter

3. Resolva: enviar o token OU abrir o widget

4. Tipos de MFA e impacto no auto-sync

5. Teste no sandbox

Próximos passos