Link Flutter SDK

This guide covers the Link Flutter SDK, version 1.x.x. If you are moving from the community plaid_flutter package, see Migrating from the community Flutter SDK.

The Plaid Link Flutter SDK is the official Flutter plugin for opening Link in iOS and Android apps. The SDK wraps Plaid's native iOS and Android SDKs and supports regular Link, Layer, Headless Link, Embedded Institution Search, and iOS FinanceKit flows.

Flutter web is not supported. For web apps, use the Link Web SDK.

To get started with Plaid Link for Flutter you'll want to sign up for free API keys through the Plaid Dashboard.

• Flutter 3.29.3 or higher
• Dart 3.7 or higher
• iOS 15.0 or higher
• Android minSdk 26 or higher

SDK versions are supported for two years; with each major SDK release, Plaid will stop officially supporting any previous SDK versions that are more than two years old. While these older versions are expected to continue to work without disruption, Plaid will not provide assistance with unsupported SDK versions.

In your Flutter project directory, run:

flutter pub add plaid_link_flutter

Or add the package to your pubspec.yaml:

dependencies:
  plaid_link_flutter: ^1.0.0

Then import it:

import 'package:plaid_link_flutter/plaid_link_flutter.dart';

Set your host app deployment target to iOS 15.0 or later:

platform :ios, '15.0'

Then install pods from your host app:

cd ios && pod install

The Flutter SDK vendors LinkKit 7.1.0 as an iOS device and simulator framework. Mac Catalyst is not supported.

Xcode 16.1 or higher is required.

For Identity Verification flows, add NSCameraUsageDescription to your app's Info.plist if your Link token can require document or selfie capture.

Set your host app minSdk to 26 or later:

android {
  defaultConfig {
    minSdk = 26
  }
}

The Flutter SDK depends on the Android Link SDK 6.2.0. Most apps do not need additional ProGuard or R8 rules. If your release build uses custom aggressive shrinking and strips the Flutter plugin, keep the plugin package:

-keep class com.plaid.plaid_link_flutter.** { *; }

For Identity Verification flows, add the camera and audio permissions required by your configured Plaid products to the host app manifest.

• Register your Android package name in the Dashboard. This is required in order to connect to OAuth institutions (which includes most major banks).

Sample app

For a sample app that demonstrates a minimal integration with the Flutter SDK, see the Plaid Link Flutter GitHub repo.

Before you can open Link, you need to first create a link_token. A link_token can be configured for different Link flows and is used to control much of Link's behavior. To see how to create a new link_token, see the API Reference entry for /link/token/create. If your Flutter application will be used on Android, the /link/token/create call should include the android_package_name parameter. Each time you open Link, you will need to get a new link_token from your server.

Next, create and retain a PlaidLinkSession, then call open on that session. Create the session as soon as the screen is ready so Link can load before the user taps your button.

PlaidLinkSession? _linkSession;
bool _linkReady = false;

Future<void> createLink(String linkToken) async {
  _linkSession = await createPlaidLinkSession(
    LinkTokenConfiguration(
      token: linkToken,
      onSuccess: (success) {
        handleSuccess(success);
      },
      onExit: (exit) {
        handleExit(exit);
      },
      onEvent: (event) {
        handleEvent(event);
      },
      onLoad: () {
        setState(() => _linkReady = true);
      },
    ),
  );
}

Layer and Headless Link use their own session creation methods: createPlaidLayerSession and createPlaidHeadlessSession. Use a Link token that is compatible with the flow you are creating.

Future<void> openLink() async {
  if (!_linkReady) return;
  await _linkSession?.open();
}

To request a fullscreen presentation on iOS, pass true to open:

await _linkSession?.open(true);

The fullscreen flag has no effect on Android, where Link opens in its own Activity.

PlaidLink is not a widget and is not used to open Link — use the session APIs shown above for that. It exposes two process-wide statics.

The PlaidLink.sdkVersion property returns the native Plaid SDK version, not the Flutter package version:

final sdkVersion = await PlaidLink.sdkVersion;

The PlaidLink.onEvent stream is available for advanced process-wide event observers. Prefer per-session onEvent callbacks for most integrations.

Future<void> handleSuccess(LinkSuccess success) async {
  // If using Item-based products, exchange public_token
  // for access_token
  await exchangePublicToken(
    publicToken: success.publicToken,
    linkSessionId: success.metadata.linkSessionId,
  );
}

void handleExit(LinkExit exit) {
  supportHandler.report({
    'error': exit.error,
    'institution': exit.metadata.institution,
    'linkSessionId': exit.metadata.linkSessionId,
    'requestId': exit.metadata.requestId,
    'status': exit.metadata.status,
  });
}

The Flutter SDK emits onEvent callbacks throughout the account linking process. The HANDOFF event can arrive after onSuccess; it indicates that Link has handed control back to your app and is useful for conversion analytics.

void handleEvent(LinkEvent event) {
  analytics.track('plaid_link_event', {
    'eventName': event.eventName.value,
    'linkSessionId': event.metadata.linkSessionId,
  });
}

Layer sessions can receive customer data, such as a phone number, before opening Link. Create the session with a Layer-compatible Link token, then call submit() on the retained session.

PlaidLayerSession? _layerSession;

Future<void> createLayer(String linkToken) async {
  _layerSession = await createPlaidLayerSession(
    LayerTokenConfiguration(
      token: linkToken,
      onSuccess: (success) {
        handleLayerSuccess(success);
      },
    ),
  );
}

Future<void> submitPhoneNumber() async {
  await _layerSession?.submit(
    const SubmissionData(
      phoneNumber: '+14155550123',
    ),
  );
}

Sessions clean up their own callbacks: success and exit callbacks dispose active listeners automatically. Call dispose() yourself only if you create a session but abandon it before opening.

_linkSession?.dispose();

Using Plaid Link with an OAuth flow requires some additional setup instructions. For details, see the OAuth guide.

For iOS, configure your Plaid redirect URI as a Universal Link in the Plaid Dashboard and in your app entitlements. For Android, register your app package name in the Plaid Dashboard and pass android_package_name when creating Link tokens. The Flutter SDK does not expose a separate OAuth resume method; OAuth return handling is managed by the native Plaid SDKs and your app's platform configuration.

The latest version of the SDK is available from GitHub. New versions of the SDK are released frequently. Major releases occur annually. The Link SDK uses Semantic Versioning, ensuring that all non-major releases are non-breaking, backwards-compatible updates. We recommend you update regularly (at least once a quarter, and ideally once a month) to ensure the best Plaid Link experience in your application.

SDK versions are supported for two years; with each major SDK release, Plaid will stop officially supporting any previous SDK versions that are more than two years old. While these older versions are expected to continue to work without disruption, Plaid will not provide assistance with unsupported SDK versions.

plaid_flutter is a community-maintained package. It is not built, released, or supported by Plaid. plaid_link_flutter is Plaid's official plugin: it wraps the same native iOS and Android SDKs that back Plaid's other mobile SDKs, is covered by Plaid Support, and follows the session-based API shape used by the React Native, iOS, and Android SDKs.

The main change when migrating is the move from a global handler API to explicit session objects. Instead of calling PlaidLink.create() and then PlaidLink.open(), create a session for the flow you want to run, retain that session in your widget state, and call methods on it.

For example, opening standard Link with the community package uses global streams and static methods:

PlaidLink.onSuccess.listen((success) => handleSuccess(success));
PlaidLink.onExit.listen((exit) => handleExit(exit));
PlaidLink.onEvent.listen((event) => print(event.name));

await PlaidLink.create(
  configuration: LinkTokenConfiguration(token: linkToken),
);
await PlaidLink.open();

The official SDK replaces this with a retained session that owns its own callbacks:

PlaidLinkSession? _linkSession;

Future<void> createLink(String linkToken) async {
  _linkSession = await createPlaidLinkSession(
    LinkTokenConfiguration(
      token: linkToken,
      onSuccess: handleSuccess,
      onExit: handleExit,
      onEvent: (event) => print(event.eventName),
    ),
  );
}

await _linkSession?.open();

For the full migration, including Layer, Headless Link, Embedded Institution Search, FinanceKit, and a migration checklist, see the migration guide on GitHub.