Link React Native SDK

Reference for integrating with the Link React Native SDK

This guide covers the latest major version of the Link React Native SDK, which is version 7.x. If you are using an older version of the SDK, consult the 5.x to 7.x or 6.x to 7.x migration guides.

Overview

To get started with Plaid Link for React Native youʼll want to sign up for free API keys through the Plaid Developer Dashboard.

Examples of Plaid Link for React Native

These docs cover the 7.x.x version of the Link React Native SDK that will feature TypeScript support. Please note that this version is still under development, though a release candidate is available.

Requirements

A new version of the React Native SDK will be released around the 20th of every month. You should keep your version up-to-date to provide the best Plaid Link experience in your application.

Version Compatibility
React Native SDKAndroid SDKiOS SDKStatus
7.x.x3.2.x>=2.0.7Active
6.x.x3.x.x>=2.0.1Active
5.x.x2.1.x>=1.1.34Active
4.x.x2.0.x<=1.1.33Active
3.x.x1.x.x<=1.1.33Deprecated
2.x.x0.3.x<=1.1.27Deprecated
1.x.x< 0.3.x<=1.1.24Deprecated

Getting Started

Installing the SDK

In your react-native project directory, run:

1
npm install --save react-native-plaid-link-sdk

Next Steps

Opening Link

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 React Native 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.

PlaidLink

PlaidLink is the the React component used to open Link from a React Native application. PlaidLink renders a Pressable component, which wraps the component you provide and intercepts onPress events to open Link.

plaidLink
onSuccessLinkSuccessListener
A function that is called when a user has successfully linked an Item. The function should expect one argument.
tokenConfigLinkTokenConfiguration
A configuration used to open Link with a Link Token.
tokenstring
The link_token to be used to authenticate your app with Link. The link_token is created by calling /link/token/create and is a short lived, one-time use token that should be unique for each Link session. In addition to the primary flow, a link_token can be configured to launch Link in update mode for Items with expired credentials, or the Payment Initiation (UK and Europe) flow. See the /link/token/create endpoint for a full list of configurations.
logLevelLinkLogLevel
Set the level at which to log statements
Possible values: DEBUG, INFO, WARN, ERROR
extraParamsRecord<string, any>
You do not need to use this field unless specifically instructed to by Plaid.
onExitLinkExitListener
A function that is called when a user has specifically exited the Link flow. The function should expect one argument.
childrenReact.ReactNode
The underlying component to render
1
2
3
4
5
6
7
8
9
10
11
12
13
<PlaidLink
tokenConfig={{
token: '#GENERATED_LINK_TOKEN#',
}}
onSuccess={(success: LinkSuccess) => {
console.log(success);
}}
onExit={(exit: LinkExit) => {
console.log(exit);
}}
>
<Text>Add Account</Text>
</PlaidLink>

onSuccess

The method is called when a user has successfully onboarded their account. The onSuccess handler returns a LinkConnection class that includes the public_token, and additional Link metadata in the form of a LinkConnectionMetadata class.

onSuccess
publicTokenString
Displayed once a user has successfully linked their Item.
metadataLinkSuccessMetadata
Displayed once a user has successfully linked their Item.
accountsArray<LinkAccount>
A list of accounts attached to the connected Item. If Select Account is enabled via the developer dashboard, accounts will only include selected accounts.
idstring
The Plaid account_id
namestring
The official account name
maskstring
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user.
typeLinkAccountType
The account type. See the Account schema for a full list of possible values
subtypeLinkAccountSubtype
The account subtype. See the Account schema for a full list of possible values
verification_statusLinkAccountVerificationStatus
When micro-deposit-based verification is being used, the accounts object includes an Item's verification_status
pending_automatic_verification
The Item is pending automatic verification
pending_manual_verification
The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified
The Item has successfully been automatically verified
manually_verified
The Item has successfully been manually verified
verification_expired
Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed
The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.ents
institutionobject
An institution object
namestring
The full institution name, such as 'Wells Fargo'
idstring
The Plaid institution identifier
linkSessionIdString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
metadataJsonMap
The data directly returned from the server with no client side changes.
1
2
3
4
5
6
7
8
9
10
11
const onSuccess = (success: LinkSuccess) => {
fetch('https://yourserver.com/exchange_public_token', {
method: 'POST',
body: {
publicToken: linkSuccess.publicToken,
accounts: linkSuccess.metadata.accounts,
institution: linkSuccess.metadata.institution,
linkSessionId: linkSuccess.metadata.linkSessionId,
},
});
};

onExit

The onExit handler is called when a user exits the Link flow prematurely or when an error occurs during Link initialization. The PlaidError returned from the onExit handler is meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant info in Plaid Support requests for the user.

onExit
errorLinkError
An object that contains the error type, error code, and error message of the error that was last encountered by the user. If no error was encountered, error will be null.
displayMessageString
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
errorCodeLinkErrorCode
The particular error code. Each errorType has a specific set of errorCodes. A code of 499 indicates a client-side exception.
errorTypeLinkErrorType
A broad categorization of the error.
errorMessageString
A developer-friendly representation of the error code.
errorJsonString
The data directly returned from the server with no client side changes.
metadataMap<String, Object>
An object containing information about the exit event
linkSessionIdString
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
institutionLinkInstitution
An institution object
namestring
The full institution name, such as 'Wells Fargo'
idstring
The Plaid institution identifier
statusLinkExitMetadataStatus
The point at which the user exited the Link flow. One of the following values
requires_questions
User prompted to answer security questions
requires_selections
User prompted to answer multiple choice question(s)
requires_recaptcha
User prompted to solve a ReCAPTCHA challenge
requires_code
User prompted to provide a one-time passcode
choose_device
User prompted to select a device on which to receive a one-time passcode
requires_credentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
requires_oauth
User prompted to enter an OAuth flow
institution_not_found
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
An exit status that is not handled by the current version of the SDK
requestIdString
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation
metadataJsonMap
The data directly returned from the server with no client side changes.
1
2
3
4
5
6
7
8
9
const onExit = (linkExit: LinkExit) => {
supportHandler.report({
error: linkExit.error,
institution: linkExit.metadata.institution,
linkSessionId: linkExit.metadata.linkSessionId,
requestId: linkExitlinkExit.metadata.requestId,
status: linkExit.metadata.status,
});
};

onEvent

The React Native Plaid module emits onEvent events throughout the account linking process. To receive these events use the usePlaidEmitter hook.

The onEvent callback is called at certain points in the Link flow. Unlike the handlers for onSuccess, onExit, and onCancelled, the onEvent handler is initialized as a global lambda passed to the Plaid class. OPEN events will be sent immediately upon Link’s opening, and remaining events will be sent by the time onSuccess or onExit is called. If you need the exact time when an event happened, use the timestamp property.
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR. The remaining callback events are informational and subject to change, and therefore should not be used to customize your product experience.

onEvent
eventNameLinkEventName
A string representing the event that has just occurred in the Link flow.
CLOSE_OAUTH
The user closed the third-party website or mobile app without completing the OAuth flow.
ERROR
A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT
The user has exited without completing the Link flow and the onExit callback is fired.
FAIL_OAUTH
The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF
The user has completed the Link flow and the onSuccess callback is fired.
OPEN
The user has opened Link.
OPEN_MY_PLAID
The user has opened my.plaid.com. This event is only sent when Link is initialized with assets as a product.
OPEN_OAUTH
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
MATCHED_SELECT_INSTITUTION
The user selected an institution that was presented as a matched institution.
MATCHED_SELECT_VERIFY_METHOD
The user selected a verification method for a matched institution.
SEARCH_INSTITUTION
The user has searched for an institution.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
The user selected an institution.
SUBMIT_CREDENTIALS
The user has submitted credentials.
SUBMIT_MFA
The user has submitted MFA.
TRANSITION_VIEW
The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
UNKNOWN
The UNKNOWN event indicates that the event is not handled by the current version of the SDK.
metadataLinkEventMetadata
An object containing information about the event.
errorCodeString
The error code that the user encountered. Emitted by: ERROR, EXIT.
errorMessageString
The error message that the user encountered. Emitted by: ERROR, EXIT.
errorTypeString
The error type that the user encountered. Emitted by: ERROR, EXIT.
exitStatusString
The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institutionIdString
The ID of the selected institution. Emitted by: all events.
institutionNameString
The name of the selected institution. Emitted by: all events.
institutionSearchQueryString
The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
linkSessionIdString
The linkSessionId is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
mfaTypeString
If set, the user has encountered one of the following MFA types: code device questions selections. Emitted by: SUBMIT_MFA and TRANSITION_VIEW when view_name is MFA.
requestIdString
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
selectionString
The verification method for a matched institution selected by the user. Possible values are phoneotp, password. Emitted by: MATCHED_SELECT_VERIFY_METHOD.
timestampString
An ISO 8601 representation of when the event occurred. For example, 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewNameLinkEventViewName
The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
CONNECTED
The user has connected their account.
CONSENT
We ask the user to consent to the privacy policy.
CREDENTIAL
Asking the user for their account credentials.
ERROR
An error has occurred.
EXIT
Confirming if the user wishes to close Link.
LOADING
Link is making a request to our servers.
MATCHED_CONSENT
We ask the matched user to consent to the privacy policy and SMS terms.
MATCHED_CREDENTIAL
We ask the matched user for their account credentials to a matched institution.
MATCHED_MFA
We ask the matched user for MFA authentication to verify their identity.
MFA
The user is asked by the institution for additional MFA authentication.
NUMBERS
The user is asked to insert their account and routing numbers.
RECAPTCHA
The user was presented with a Google reCAPTCHA to verify they are human.
SELECT_ACCOUNT
We ask the user to choose an account.
SELECT_BRAND
The user selected a brand, e.g. Bank of America. The brand selection interface occurs before the institution select pane and is only provided for large financial institutions with multiple online banking portals.
SELECT_INSTITUTION
We ask the user to choose their institution.
1
2
3
usePlaidEmitter((event) => {
console.log(event);
});

OAuth

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

Upgrading