Flutter

O pacote flutter_malvo_connect embute o widget hospedado do Malvo Connect ({baseUrl}/connect?token=...) numa view webview_flutter e converte os eventos postMessage do widget em callbacks Dart.

A conectividade fala com um único host de API, https://api.malvo.io. O widget e o dashboard ficam em https://malvo.io. Não há iniciação de pagamento (ITP) — o widget só conduz consentimentos de agregação de dados (Items).

Pré-requisitos

O único dado obrigatório é um Connect Token gerado pelo seu backend (POST /auth → apiKey → POST /connect_token → accessToken, TTL de 30 minutos). Nunca embarque clientId/clientSecret no app — eles ficam só no servidor.

Instalação

Adicione a dependência ao pubspec.yaml:

dependencies:
  flutter_malvo_connect:
    git: https://github.com/malvo-io/flutter_malvo_connect

O setup de WebView segue o webview_flutter: no Android exige minSdkVersion 19+; no iOS não há configuração extra obrigatória.

Uso

O widget MalvoConnect é um Widget que você coloca dentro de um Scaffold:

import 'package:flutter/material.dart';
import 'package:flutter_malvo_connect/flutter_malvo_connect.dart';

class ConnectPage extends StatelessWidget {
  const ConnectPage({super.key, required this.connectToken});
  final String connectToken;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: MalvoConnect(
          connectToken: connectToken,
          baseUrl: 'https://malvo.io', // origem que serve o widget
          includeSandbox: true,        // somente em dev
          onSuccess: (data) {
            // data = { item: { id, status, connector, ... } }
            debugPrint('connected item ${data['item']['id']}');
            Navigator.of(context).pop(data['item']);
          },
          onError: (error) {
            // error = { code, message, itemId? }
            debugPrint('error ${error['code']}: ${error['message']}');
          },
          onClose: () => Navigator.of(context).maybePop(),
          onEvent: (event) => debugPrint('event $event'),
        ),
      ),
    );
  }
}

Webhooks são a fonte da verdade. O onSuccess é uma conveniência de UX — o usuário pode fechar o app antes dele disparar. Persista as conexões a partir dos webhooks item/created / item/updated no seu backend. Veja Webhooks.

Fluxo de atualização (update item)

Para reautenticar um item existente, gere um update token com itemId no corpo do POST /connect_token e passe o mesmo id em updateItem:

MalvoConnect(
  connectToken: updateToken,
  updateItem: 'item-id-uuid',
  onSuccess: (data) => debugPrint(data['item']['status']),
)

Open Finance / OAuth

Por padrão o consentimento bancário roda dentro da WebView: o widget redireciona ao banco e retoma via /connect/finish automaticamente — sem setup extra. Para instituições que recusam WebViews embarcadas, configure oauthRedirectUri com o deep link completo:

Passe o oauthRedirectUri ao gerar o token

No POST /connect_token do seu backend, informe options.oauthRedirectUri casando com o scheme, ex.: malvo://oauth-callback.

Defina oauthRedirectUri no widget

Passe oauthRedirectUri: Uri.parse('malvo://oauth-callback') ao MalvoConnect.

Registre o scheme nativamente

Declare no Android (AndroidManifest.xml, intent-filter) e no iOS (Info.plist, CFBundleURLTypes).

No retorno, o SDK compara scheme, host, porta, caminho, userinfo e qualquer query estática do URI configurado, além de exigir que o malvoFlowId reservado corresponda ao connectTokenId do Connect Token atual, antes de retomar a rota autenticada /connect?token=...&resumeItemId=.... Após recriar o processo, o host precisa restaurar com segurança o mesmo Connect Token ainda válido; o SDK não o persiste e o callback não carrega bearer. A bridge exige malvoBridgeNonce igual ao claim separado bridgeNonce e remove o campo antes dos callbacks. Bearer, códigos bancários e malvoFlowId nunca são encaminhados à WebView. Não adicione parâmetros reservados manualmente.

<activity android:name=".MainActivity">
  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="malvo" android:host="oauth-callback" />
  </intent-filter>
</activity>

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>malvo</string>
    </array>
  </dict>
</array>

Parâmetros

String

required

O Connect Token de 30 minutos gerado pelo seu backend. Único parâmetro obrigatório.

String

default:"https://malvo.io"

Origem que serve o widget hospedado.

bool

Exibe conectores de sandbox (somente em dev).

String?

Id de um item para o fluxo de atualização. O token deve ter sido gerado com esse itemId.

Uri?

URI completo do app (ex.: Uri.parse('malvo://oauth-callback')) para validar e capturar o retorno do OAuth no navegador do sistema.

String?

Compatibilidade legada baseada somente no scheme. Não use em novas integrações.

Parâmetro	Tipo	Notas
`connectToken`	`String`	Obrigatório. Token de 30 min do seu backend.
`baseUrl`	`String`	Origem que serve o widget. Padrão `https://malvo.io`.
`includeSandbox`	`bool`	Exibe conectores de sandbox.
`updateItem`	`String?`	Id do item para o fluxo de atualização.
`connectorTypes` / `connectorIds` / `countries` / `language` / `selectedConnectorId`	—	Filtros / dicas de UX.
`oauthRedirectUri`	`Uri?`	URI completo preferencial para validar o retorno OAuth externo.
`oauthRedirectScheme`	`String?`	Legado; valida somente o scheme.

Callbacks

Callback	Assinatura	Dispara quando
`onSuccess`	`(data)` onde `data = { item: {...} }`	Conexão (ou atualização) concluída.
`onError`	`(error)` onde `error = { code, message, itemId? }`	Falha na conexão.
`onOpen`	`()`	Widget exibido.
`onClose`	`()`	Widget fechado (sucesso ou cancelamento).
`onEvent`	`(event)`	Recebe `OPEN`, `malvo:success`, `malvo:error` e `malvo:close`; falhas de abertura/retomada também usam `malvo:error`.

Próximos passos

Connect Widget — opções completas do widget.
Webhooks — a fonte da verdade para persistir conexões.

Visão geral

Web & JavaScript

Mobile

Pré-requisitos

Instalação

Uso

Fluxo de atualização (update item)

Open Finance / OAuth

Parâmetros

Callbacks

Próximos passos

​Pré-requisitos

​Instalação

​Uso

​Fluxo de atualização (update item)

​Open Finance / OAuth

​Parâmetros

​Callbacks

​Próximos passos

Pré-requisitos

Instalação

Uso

Fluxo de atualização (update item)

Open Finance / OAuth

Parâmetros

Callbacks

Próximos passos