Skip to content

api-reference.md

Latest commit

 

History

History
249 lines (198 loc) · 8.92 KB

api-reference.md

File metadata and controls

249 lines (198 loc) · 8.92 KB
Raw

API Reference

This document summarizes the public Dart API and payload model shapes. Pub.dev also generates Dart API documentation from this package after release. Locally, run:

dart doc

Public Methods

API Returns Description
createPlaidLinkSession(LinkTokenConfiguration config) Future<PlaidLinkSession> Creates a regular Link session.
PlaidLinkSession.open([bool fullScreen = false]) Future<void> Opens the regular Link session.
createPlaidLayerSession(LayerTokenConfiguration config) Future<PlaidLayerSession> Creates a Layer session.
PlaidLayerSession.open() Future<void> Opens the Layer session.
PlaidLayerSession.submit(SubmissionData data) Future<void> Submits user-collected data to Layer.
createPlaidHeadlessSession(LinkTokenConfiguration config) Future<PlaidHeadlessSession> Creates a Headless session.
PlaidHeadlessSession.start() Future<void> Starts the Headless session.
PlaidLinkSession.dispose() (also on Layer/Headless) void Cancels the session's callbacks. Runs automatically after a terminal exit, or after the terminal HANDOFF event that follows success (with a short fallback if HANDOFF never arrives); call it to abandon a session created but never opened.
syncFinanceKit(FinanceKitConfiguration config) Future<void> Runs iOS FinanceKit sync. Android throws FinanceKitException.
PlaidLink.sdkVersion Future<String?> Returns the native Plaid SDK version, not the Flutter package version.
PlaidLink.onEvent Stream<LinkEvent> Process-wide event stream for advanced observers. Prefer per-session callbacks.

Event delivery and session lifecycle

onEvent receives every Link event, including the terminal HANDOFF event. Plaid sends HANDOFF after onSuccess — it signals that Link has handed control back to your app, and Plaid uses it for conversion analytics — so the session keeps its listeners alive briefly after success to deliver it. The session then disposes itself automatically when HANDOFF arrives, or after a short fallback window if it never does (so nothing leaks). onExit remains an immediate teardown; no HANDOFF follows an exit.

Configuration Types

LinkTokenConfiguration

Field Type Nullable Notes
token String No Link token generated by your backend.
onSuccess void Function(LinkSuccess) No Terminal callback.
onExit void Function(LinkExit) No Terminal callback.
onEvent void Function(LinkEvent) No Non-terminal callback.
onLoad void Function() Yes Called after native create/load completes.

LayerTokenConfiguration

Field Type Nullable Notes
token String No Layer-compatible link token.
onSuccess void Function(LinkSuccess) No Terminal callback.
onExit void Function(LinkExit) Yes Terminal callback.
onEvent void Function(LinkEvent) Yes Non-terminal callback.

PlaidEmbeddedSearchView

Constructor argument Type Nullable Notes
token String No Embedded-compatible link token.
onSuccess void Function(LinkSuccess) Yes Terminal callback.
onExit void Function(LinkExit) Yes Terminal callback.
onEvent void Function(LinkEvent) Yes Non-terminal callback.
onLoad void Function() Yes Called when the embedded view loads.

Result Models

Several fields use typed "wire value" wrappers (LinkEventName, LinkViewName, LinkExitStatus, LinkVerificationStatus, LinkErrorType). Each exposes named constants (e.g. LinkEventName.openOauth) mirroring the values Plaid's native SDKs emit, a raw String value, and value equality. An unrecognized value is preserved verbatim (LinkEventName('SOMETHING_NEW')) rather than dropped, so new SDK values never crash a consumer. Compare with the constant (event.eventName == LinkEventName.error) or read event.eventName.value.

LinkSuccess

Field Type Nullable
publicToken String No
metadata LinkSuccessMetadata No

LinkSuccessMetadata

Field Type Nullable
institution LinkInstitution Yes
accounts List<LinkAccount> No
linkSessionId String No
metadataJson String Yes

LinkExit

Field Type Nullable
error LinkError Yes
metadata LinkExitMetadata No

LinkExitMetadata

Field Type Nullable
status LinkExitStatus Yes
institution LinkInstitution Yes
linkSessionId String No
requestId String No
metadataJson String Yes

LinkEvent

Field Type Nullable
eventName LinkEventName No
metadata LinkEventMetadata No

LinkEventMetadata

Field Type Nullable
accountNumberMask String Yes
linkSessionId String No
mfaType String Yes
requestId String Yes
viewName LinkViewName No
errorCode String Yes
errorMessage String Yes
errorType LinkErrorType Yes
exitStatus LinkExitStatus Yes
institutionId String Yes
institutionName String Yes
institutionSearchQuery String Yes
isUpdateMode bool Yes
matchReason String Yes
routingNumber String Yes
issueId String Yes
issueDescription String Yes
issueDetectedAt String Yes
selection String Yes
timestamp DateTime Yes
metadataJson String Yes

LinkError

Field Type Nullable
errorCode String No
errorType LinkErrorType No
errorMessage String No
displayMessage String Yes
errorJson String Yes

LinkInstitution

Field Type Nullable
id String No
name String No

LinkAccount

Field Type Nullable
id String No
name String Yes
mask String Yes
type String No
subtype String No
verificationStatus LinkVerificationStatus Yes

Layer Submission

SubmissionData

Field Type Nullable
phoneNumber String Yes
dateOfBirth String Yes
params Map<String, String> Yes

FinanceKit

FinanceKitConfiguration

Field Type Nullable Default
token String No None
requestAuthorizationIfNeeded bool No true
syncBehavior FinanceKitSyncBehavior No FinanceKitSyncBehavior.live

FinanceKitSyncBehavior

Value Native value
FinanceKitSyncBehavior.live 0
FinanceKitSyncBehavior.simulated 1

FinanceKitException

Field Type Nullable
type FinanceKitErrorType No
code String No
message String No

FinanceKitErrorType

Value Mapped platform code
FinanceKitErrorType.invalidToken INVALID_TOKEN
FinanceKitErrorType.permissionError PERMISSION_ERROR
FinanceKitErrorType.linkApiError LINK_API_ERROR
FinanceKitErrorType.permissionAccessError PERMISSION_ACCESS_ERROR
FinanceKitErrorType.unsupportedAndroid UNSUPPORTED_ANDROID
FinanceKitErrorType.unsupportedIosVersion UNSUPPORTED_IOS_VERSION
FinanceKitErrorType.unknown Any other code.

Link Errors

PlaidLinkException

Thrown by createPlaidLinkSession, the session open/start calls, and Layer submit. (syncFinanceKit throws FinanceKitException instead.) The raw platform code is always preserved; type is unknown for any code not modeled below.

Field Type Nullable
type PlaidLinkErrorType No
code String No
message String No
details Object? Yes

PlaidLinkErrorType

Value Mapped platform code
PlaidLinkErrorType.invalidToken INVALID_TOKEN
PlaidLinkErrorType.linkSessionCreateError LINK_SESSION_CREATE_ERROR
PlaidLinkErrorType.layerSessionCreateError LAYER_SESSION_CREATE_ERROR
PlaidLinkErrorType.headlessSessionCreateError HEADLESS_SESSION_CREATE_ERROR
PlaidLinkErrorType.noActivity PLAID_NO_ACTIVITY
PlaidLinkErrorType.noViewController PLAID_NO_VC
PlaidLinkErrorType.noLayerSession PLAID_NO_LAYER_SESSION
PlaidLinkErrorType.noSession PLAID_NO_SESSION
PlaidLinkErrorType.openError PLAID_OPEN_ERROR
PlaidLinkErrorType.submitError PLAID_SUBMIT_ERROR
PlaidLinkErrorType.unknown Any other code.