flutter_malvo_connect

Malvo Connect SDK for Flutter — link a user's bank accounts (Open Finance Brasil) through the hosted Malvo Connect widget, talking to your own Malvo API.

It wraps the hosted widget ({baseUrl}/connect?token=...) in a webview_flutter view and bridges its postMessage events to Dart callbacks.

Install

dependencies:
  flutter_malvo_connect:
    path: ../packages/flutter_malvo_connect # or a git/pub ref

WebView platform setup (Android minSdkVersion 19+, iOS) follows webview_flutter.

Usage

The only required input is a Connect Token minted by your backend (POST /auth → apiKey → POST /connect_token → accessToken, 30-min TTL). Never ship your clientId/clientSecret in the app.

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', // your malvo-web origin
          includeSandbox: true,            // dev only
          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 are the source of truth. onSuccess is a UX convenience — the user may close the app before it fires. Persist connections from the item/created / item/updated webhooks on your backend.

Parameters

Param Type Notes
connectToken String Required. 30-min token from your backend.
baseUrl String malvo-web origin. Default https://malvo.io. Use http://10.0.2.2:5173 on the Android emulator for local dev.
includeSandbox bool Show sandbox connectors.
updateItem String? Item id for an update flow (token must be minted with that itemId).
connectorTypes / connectorIds / countries / language / selectedConnectorId — Filtering / UX hints.
oauthRedirectScheme String? Custom scheme (e.g. malvo) for external-browser OAuth deep-link return.
onSuccess / onError / onOpen / onClose / onEvent callbacks Widget lifecycle callbacks.

Open Finance / OAuth

By default the bank consent runs inside the WebView: the hosted widget redirects to the bank and resumes via /connect/finish automatically — no extra setup needed.

For institutions that refuse embedded WebViews, set oauthRedirectScheme and:

  1. Pass the matching options.oauthRedirectUri (e.g. malvo://oauth-callback) to POST /connect_token on your backend.
  2. Register the scheme in AndroidManifest.xml (intent-filter) and Info.plist (CFBundleURLTypes).

On the deep-link return the widget re-loads /connect/finish and resumes.

How it works

The hosted widget forwards every malvo:* event to window.MalvoConnect.postMessage(...); this package registers that JS channel and dispatches to your callbacks. See the Malvo spec backend/docs/specs/connect-widget.md.

Libraries

flutter_malvo_connect
Malvo Connect SDK for Flutter.