Link iOS SDK

Reference for integrating with the Link iOS SDK

This guide covers the latest major version of the Link iOS SDK, which is version 2.x. If you are using an older version of the SDK, consult the migration guide.

Overview

The Plaid Link SDK is a quick and secure way to link bank accounts to Plaid from within your iOS app Link is a drop-in framework that handles connecting a financial institution to your app (credential validation, multi-factor authentication, error handling, etc).

To get started with Plaid Link for iOS, clone the GitHub repository and try out the example application, which provides a reference implementation in Swift. Youʼll want to sign up for free API keys through the Plaid Developer Dashboard to get started.

Examples of Plaid Link for iOS

Installation

Plaid Link for iOS is an embeddable framework that is bundled and distributed within your application. There are several ways to obtain the necessary files and keep them up-to-date; we recommend using CocoaPods. Regardless of what you choose, submitting a new version of your application with the updated LinkKit.xcframework to the App Store is required.

Requirements

A new version of LinkKit.xcframework will be released around the 15th of every month. We recommend you keep up to date to provide the best Plaid Link experience in your application.

Upgrading

Please see our GitHub releases for version release notes. Steps to upgrade to the latest version can be found at the iOS 1.x to 2.x migration guide.

CocoaPods
  1. If you haven’t already, install the latest version of CocoaPods.
  2. If you don’t have an existing Podfile, run the following command to create one:
    1
    pod init
  3. Add this line to your Podfile:
    1
    pod 'Plaid'
  4. Run the following command:
    1
    pod install
  5. To update to newer releases in the future, run:
    1
    pod install
Manual

Get the latest version of LinkKit.xcframework and embed it into your application.

Embed LinkKit.xcframework into your application, for example by dragging and dropping the file onto the Embed Frameworks build phase as shown below.

Depending on the location of the LinkKit.xcframework on the filesystem you may need to change the Framework Search Paths build setting to avoid the error: fatal error: 'LinkKit/LinkKit.h' file not found. For example, the LinkDemo Xcode projects have it set to FRAMEWORK_SEARCH_PATHS = $(PROJECT_DIR)/../ since the LinkKit.xcframework file is shared between them and is kept in the directory that also contains the demo project directories.

(Optional) register your redirect URI

Registering a redirect URI is required when working with OAuth, which is used for European integrations as well as integrations with some US financial institutions. For more information about OAuth flows, and whether your app needs to support them, see the OAuth guide.

To register your redirect app URI:

  1. Log into your Plaid Dashboard at the API page
  2. Next to Allowed redirect URIs click Configure then Add New URI
  3. Enter your redirect URI, for example www.plaid.com/redirect
  4. Click Save Changes. You may be prompted to re-enter your password.

These redirect URIs must be set up as universal links. For more information on universal links, see Allowing Apps and Websites to Link to Your Content.

Your iOS app is now set up and ready to start integrating with the Plaid SDK.

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 learn how to create a new link_token, see the API Reference entry for /link/token/create.

Create a LinkTokenConfiguration

Each time you open Link, you will need to get a new link_token from your server and create a new LinkTokenConfiguration object with it.

1
2
3
4
5
6
let configuration = LinkTokenConfiguration(
token: token,
onSuccess: { linkSuccess in
// Send the linkSuccess.publicToken to your app server.
}
)
Create a Handler

Create a Handler - A Handler is a one-time use object used to open a Link session. The Handler must be retained for the duration of the Plaid SDK flow. It will also be needed to respond to OAuth universal link redirects as described in the OAuth guide.

1
2
3
4
5
6
7
let result = Plaid.create(configuration)
switch result {
case .failure(let error):
logger.error("Unable to create Plaid handler due to: \(error)")
case .success(let handler):
self.handler = handler
}
Open Link

Finally, open Link by calling open on the Handler object.
This will usually be done in a button’s target action.

Starting the Plaid Link for iOS experience begins with creating a link_token. Once the link_token is passed to your app, create an instance of LinkTokenConfiguration, create a Handler using Plaid.create() passing the previously created LinkTokenConfiguration instance, and call open() on the handler passing your preferred presentation method.

create
tokenString
Specify a link_token to authenticate your app with Link. This 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 flow. See the /link/token/create endpoint for more details.
onSuccessclosure
A closure that is called when a user has successfully onboarded an Item. The closure should expect a single LinkSuccess argument, containing the publicToken String and a metadata of type SuccessMetadata
onExitclosure
A closure that is called when a user has specifically exited the Link flow. The closure should expect a single LinkExit argument, containing an optional error and a metadata of type ExitMetadata. See onExit.
onEventclosure
A closure that is called when a user reaches certain points in the Link flow. The closure should expect a single LinkEvent argument, containing an eventName enum of type EventType and a metadata of type EventMetadata.
1
2
let method: PresentationMethod = .viewController(self)
handler.open(presentUsing: method)

onSuccess

The closure is called when a user has successfully onboarded their account. It should take a single LinkSuccess argument, containing the publicToken String and a metadata of type SuccessMetadata.

onSuccess
linkSuccessLinkSuccess
Contains the publicToken and metadata for this successful flow.
publicTokenString
Displayed once a user has successfully linked their Item.
metadataLinkSuccess
Displayed once a user has successfully linked their Item.
institutionInstitution
An institution object
nameString
The full institution name, such as 'Wells Fargo'
institutionIDInstitutionID (String)
The Plaid institution identifier
accountsArray<Account>
A list of accounts attached to the connected Item
idAccountID (String)
The Plaid account_id
nameString
The official account name
maskOptional<AccountMask> (Optional<String>)
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.
subtypeAccountSubtype
The account subtype and its type. See Account Types for a full list of possible values.
verificationStatusOptional<VerificationStatus>
When micro-deposit-based verification is being used, the accounts object includes an Item's verification_status. Possible values are:
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.
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.
metadataJSONString
Unprocessed metadata, formatted as JSON, sent from the Plaid API.
1
2
3
onSuccess: { linkSuccess in
// Send the linkSuccess.publicToken to your app server.
}

onExit

The optional closure is called when a user has specifically exited the Link flow or an error occurred during Link initialization. It should take a single LinkExit argument, containing an optional error and a metadata of type ExitMetadata.

onExit
linkExitLinkExit
Contains the optional error and metadata for when the flow was exited.
errorOptional<ExitError>
An Error type that contains the errorCode, errorMessage, and displayMessage of the error that was last encountered by the user. If no error was encountered, error will be nil.
errorCodeExitErrorCode
The error code and error type that the user encountered. Each errorCode has an associated errorType, which is a broad categorization of the error.
errorMessageString
A developer-friendly representation of the error code.
displayMessageOptional<String>
A user-friendly representation of the error code or nil if the error is not related to user action. This may change over time and is not safe for programmatic use.
metadataExitMetadata
Displayed once a user has successfully linked their Item.
statusOptional<ExitStatus>
The status key indicates the point at which the user exited the Link flow.
requiresQuestions
User prompted to answer security question(s).
requiresSelections
User prompted to answer multiple choice question(s).
requiresCode
User prompted to provide a one-time passcode.
chooseDevice
User prompted to select a device on which to receive a one-time passcode.
requiresCredentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.
institutionNotFound
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
The exit status has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original exit status as sent by the Plaid API.
institutionOptional<Institution>
An institution object
institutionIDInstitutionID (String)
The Plaid specific identifier for the institution.
nameString
The full institution name, such as 'Wells Fargo'.
linkSessionIDOptional<String>
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.
requestIDOptional<String>
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
metadataJSONRawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
1
2
3
let onExit: OnExitHandler = { linkExit in
// Optionally handle linkExit data according to your application's needs
}

onEvent

This optional closure is called when certain events in the Plaid Link flow have occurred, for example, when the user selected an institution. This enables your application to gain further insight into what is going on as the user goes through the Plaid Link flow.
The following onEvent callbacks are stable, which means that they will not be deprecated or changed: open, exit, handoff, selectInstitution, error. The remaining callback events are informational and subject to change, and therefore should not be used to customize your product experience.

onEvent
linkEventLinkEvent
Contains the eventName and metadata for the Link event.
eventNameEventName
An enum representing the event that has just occurred in the Link flow.
closeOAuth
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 errorCode in the `metadata.
exit
The user has exited without completing the Link flow and the onExit callback is fired.
failOAuth
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.
matchedSelectInstitution
The user selected an institution that was presented as a matched institution.
matchedSelectVerifyMethod
The user selected a verification method for a matched institution.
open
The user has opened Link.
openMyPlaid
The user has opened my.plaid.com. This event is only sent when Link is initialized with Assets as a product.
openOAuth
The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
searchInstitution
The user has searched for an institution.
selectBrand
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.
selectInstitution
The user selected an institution.
submitCredentials
The user has submitted credentials.
submitMFA
The user has submitted MFA.
transitionView
The transitionView event indicates that the user has moved from one view to the next.
unknown
The event has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original event name as sent by the Plaid API.
metadataEventMetadata struct
An object containing information about the event
errorCodeOptional<ExitErrorCode>
The error code that the user encountered. Emitted by: error, exit.
errorMessageOptional<String>
The error message that the user encountered. Emitted by: error, exit.
exitStatusOptional<ExitStatus>
The status key indicates the point at which the user exited the Link flow. Emitted by: exit.
requiresQuestions
User prompted to answer security question(s).
requiresSelections
User prompted to answer multiple choice question(s).
requiresCode
User prompted to provide a one-time passcode.
chooseDevice
User prompted to select a device on which to receive a one-time passcode.
requiresCredentials
User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution.
institutionNotFound
User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution
unknown
The exit status has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original exit status as sent by the Plaid API.
institutionIDOptional<InstitutionID> (Optional<String>)
The ID of the selected institution. Emitted by: all events.
institutionNameOptional<String>
The name of the selected institution. Emitted by: all events.
institutionSearchQueryOptional<String>
The query used to search for institutions. Emitted by: searchInstitution.
linkSessionIDString
The link_session_id 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.
mfaTypeOptional<MFAType>
If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: submitMFA and transitionView when viewName is mfa
requestIDOptional<String>
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
selectionOptional<String>
The verification method for a matched institution selected by the user. Possible values are phoneotp, password. Emitted by: matchedSelectVerifyMethod.
timestampDate
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewNameOptional<ViewName>
The name of the view that is being transitioned to. Emitted by: transitionView.
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.
matchedConsent
We ask the matched user to consent to the privacy policy and SMS terms.
matchedCredential
We ask the matched user for their account credentials to a matched institution.
matchedMfa
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.
selectAccount
We ask the user to choose an account.
selectBrand
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.
selectInstitution
We ask the user to choose their institution.
unknown
The view has not been defined in the current version of the SDK. The unknown case has an associated value carrying the original view name as sent by the Plaid API.
metadataJSONRawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
1
2
3
configuration.onEvent = { linkEvent in
// Optionally handle linkEvent data according to your application's needs
}

OAuth

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