Plaid logo
Docs
ALL DOCS

Link

  • Overview
Libraries
  • Web
  • iOS
  • Android
  • React Native
  • Webview
Core Link flows
  • OAuth guide
  • Update mode
  • Preventing duplicate Items
  • Data Transparency Messaging migration
  • Account Select v2 migration guide
  • Link Token migration guide
  • Legacy public key integrations
Optimizing Link
  • Optimizing Link conversion
  • Measuring Link conversion
  • Pre-Link messaging
  • Customizing Link
  • Choosing when to inititalize products
  • Returning user experience
  • Modular Link (UK/EU only)
Errors and troubleshooting
  • Troubleshooting
  • Handling an invalid Link Token
  • Institution status in Link
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

Link iOS SDK

Reference for integrating with the Link iOS SDK

To maintain support for Chase OAuth flows, all integrations must upgrade to version 4.1.0 of the Link iOS SDK (released January 2023) by June 30, 2023. If you are using version 2.x.x of the SDK, consult the migration guide. If you are using version 3.x.x, the only migration step required is to use XCode 14.

Overview

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

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

Examples of Plaid Link for iOS

Initial iOS setup

Before writing code using the SDK, you must first perform some setup steps to register your app with Plaid and configure your project.

The "Register your redirect URI" and "Set up Universal Links" steps describe setting up your app for OAuth redirects. If your integration uses only Identity Verification or Monitor, they can be skipped; they are mandatory otherwise.

Register your redirect URI
  1. Sign in to the Plaid Dashboard and go to the Team Settings -> API page.
  2. Next to Allowed redirect URIs click Configure then Add New URI.
  3. Enter your redirect URI, which you must also set up as a Universal Link for your application, for example: https://app.example.com/plaid/.
  4. Click Save Changes.

These redirect URIs must be set up as Universal Links in your application. For details, see Apple's documentation on Allowing Apps and Websites to Link to Your Content.

Plaid does not support registering URLs with custom URL schemes as redirect URIs since they lack the security of Universal Links through the two-way association between your app and your website. Any application can register custom URL schemes and there is no further validation from iOS. If multiple applications have registered the same custom URL scheme, a different application may be launched each time the URL is opened. To complete Plaid OAuth flows, it is important that your application is opened and not any arbitrary application that has registered the same URL scheme.

Set up Universal Links

In order for Plaid to return control back to your application after a user completes a bank's OAuth flow, you must specify a redirect URI, which will be the URI from which Link will be re-launched to complete the OAuth flow. The redirect URI must be a Universal Link. An example of a typical redirect URI is: https://app.example.com/plaid.

Universal Links consist of the following parts:

  • An applinks entitlement for the Associated Domains capability in your app. For details, see Apple’s documentation on the Associated Domains Entitlement and the entitlements example in the LinkDemo-Swift example app.
  • Code in your app handling the user activity when your app is opened via Universal Links. For details, see Apple's documentation on Supporting Universal Links in your app and the AppDelegate example in the LinkDemo-Swift example app. The Plaid Link SDK will ignore unexpected URLs passed to continue(from:) as per Apple’s recommendations, so there is no need to filter out unrelated URLs. Doing so may prevent a valid URL from being passed to continue(from:) and OAuth may not continue as expected.
  • An apple-app-site-association file on your website. For details, see Apple’s documentation on Supporting Associated Domains and see our minimal example below.

There are a few requirements for apple-app-site-association files:

  • Must be a static JSON file
  • Must be hosted using a https:// scheme with a valid certificate and no redirects
  • Must be hosted at https://<my-fully-qualified-domain>/.well-known/apple-app-site-association

Below is an example for https://my-app.com (https://my-app.com/.well-known/apple-app-site-association)

Copy
1{
2 "applinks": {
3 "details": [
4 {
5 "appIDs": [ "<My Application Identifier Prefix>.<My Bundle ID>" ],
6 "components": [
7 {
8 "/": "/plaid/*",
9 "comment": "Matches any URL path whose path starts with /plaid/"
10 }
11 ]
12 }
13 ]
14 }
15}

Once you have enabled Universal Links, your iOS app is now set up and ready to start integrating with the Plaid SDK.

Ensure that the corresponding entry for the configured redirect URI in the apple-app-site-association file on your website continues to be available. If it is removed, OAuth sessions will fail until it is available again.

Installation

Plaid Link for iOS is an embeddable framework that is bundled and distributed with your application. There are several ways to obtain the necessary files and keep them up-to-date; we recommend using Swift Package Manager or 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
LinkKit iOS versionXcode toolchain minimum supportSupported iOS versions
LinkKit 4.x.xXcode 14iOS 11 or greater
LinkKit 3.x.xXcode 13iOS 11 or greater
LinkKit 1.0.0 - 2.5.1Xcode 11.5iOS 11 or greater
Select group for content switcher
Swift Package Manager
  1. To integrate LinkKit using Swift Package Manager, Swift version >= 5.3 is required.
  2. In your Xcode project from the Project Navigator (Xcode ❯ View ❯ Navigators ❯ Project ⌘ 1) select your project, activate the Package Dependencies tab and click on the plus symbol ➕ to open the Add Package popup window:
  3. Enter the LinkKit package URL https://github.com/plaid/plaid-link-ios into the search bar in the top right corner of the Add Package popup window.
  4. Select the plaid-link-ios package.
  5. Choose your Dependency Rule (we recommend Up to Next Major Version).
  6. Select the project to which you would like to add LinkKit, then click Add Package:
  7. Select the LinkKit package product and click Add Package:
  8. Verify that the LinkKit Swift package was properly added as a package dependency to your project:
  9. Select your application target and ensure that the LinkKit library is embedded into your application:
Camera Support (Identity Verification only)

When using the Identity Verification product, the Link SDK may use the camera if a user needs to take a picture of identity documentation. To support this workflow, add a NSCameraUsageDescription entry to your application's plist with an informative string. This allows iOS to prompt the user for camera access. iOS will crash your application if this string is not provided.

Upgrading

New versions of LinkKit.xcframework are released frequently, at least once every few months. We recommend you keep up to date to provide the best Plaid Link experience in your application.

For details on each release see the GitHub releases and version release notes. To upgrade Plaid Link iOS from 1.x to 2.x, refer to the iOS 1.x to 2.x migration guide.

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.

For iOS the /link/token/create call must include the redirect_uri parameter and it must match the redirect URI you have configured with Plaid (see Register your redirect URI above).

Create a Configuration

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, then create a Handler using Plaid.create() passing the previously created LinkTokenConfiguration, and call open() on the handler passing your preferred presentation method. Note that each time you open Link, you will need to get a new link_token from your server and create a new LinkTokenConfiguration with it.

create
token
String
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.
onSuccess
closure
A required closure that is called when a user successfully links an Item. The closure should expect a single LinkSuccess argument, containing the publicToken String and a metadata of type SuccessMetadata. See onSuccess below.
onExit
closure
An optional closure that is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. The closure should expect a single LinkExit argument, containing an optional error and a metadata of type ExitMetadata. See onExit below.
onEvent
closure
An optional 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. See onEvent below.
Select Language
Copy
1var linkConfiguration = LinkTokenConfiguration(
2 token: "<#LINK_TOKEN_FROM_SERVER#>",
3 onSuccess: { linkSuccess in
4 // Send the linkSuccess.publicToken to your app server.
5 }
6)
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. For more details, see the OAuth guide.

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

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

Select Language
Copy
1let method: PresentationMethod = .viewController(self)
2handler.open(presentUsing: method)

Handling redirect URIs

When your app is opened via an Universal Link, it must check whether the opened URL is the redirect URI registered with Plaid and pass the URL to LinkKit to complete the account linking flow.

Select Language
Copy
1if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let redirectUri = userActivity.webpageURL {
2 // NOTE: Your handler must be accessible from your application delegate or scene delegate.
3 self.handler.continue(from: redirectUri)
4}

onSuccess

The closure is called when a user successfully links an Item. It should take a single LinkSuccess argument, containing the publicToken String and a metadata of type SuccessMetadata.

onSuccess
linkSuccess
LinkSuccess
Contains the publicToken and metadata for this successful flow.
publicToken
String
Displayed once a user has successfully linked their Item.
metadata
LinkSuccess
Displayed once a user has successfully linked their Item.
institution
nullableInstitution
An institution object. If the Item was created via Same-Day micro-deposit verification, will be null.
name
String
The full institution name, such as 'Wells Fargo'
institutionID
InstitutionID (String)
The Plaid institution identifier
accounts
Array<Account>
A list of accounts attached to the connected Item
id
AccountID (String)
The Plaid account_id
name
String
The official account name
mask
Optional<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.
subtype
AccountSubtype
The account subtype and its type. See Account Types for a full list of possible values.
verificationStatus
Optional<VerificationStatus>
The Item's micro-deposit-based 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.
nil: Micro-deposit-based verification is not being used for the Item.
linkSessionID
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.
metadataJSON
String
Unprocessed metadata, formatted as JSON, sent from the Plaid API.
Select Language
Copy
1onSuccess: { linkSuccess in
2 // Send the linkSuccess.publicToken to your app server.
3}

onExit

This optional closure is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. It should take a single LinkExit argument, containing an optional error and a metadata of type ExitMetadata.

onExit
linkExit
LinkExit
Contains the optional error and metadata for when the flow was exited.
error
Optional<ExitError> (Swift), Optional<NSError> (Objective-C)
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. In Objective-C, field names will match the NSError type.
errorCode
ExitErrorCode
The error code and error type that the user encountered. Each errorCode has an associated errorType, which is a broad categorization of the error.
errorMessage
String
A developer-friendly representation of the error code.
displayMessage
Optional<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.
metadata
ExitMetadata
Displayed once a user has successfully linked their Item.
status
Optional<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.
requiresAccountSelection
User prompted to select one or more financial accounts to share
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.
institution
Optional<Institution>
An institution object. If the Item was created via Same-Day micro-deposit verification, will be omitted.
institutionID
InstitutionID (String)
The Plaid specific identifier for the institution.
name
String
The full institution name, such as 'Wells Fargo'.
linkSessionID
Optional<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.
requestID
Optional<String>
The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation.
metadataJSON
RawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
Select Language
Copy
1linkConfiguration.onExit = { linkExit in
2 // Optionally handle linkExit data according to your application's needs
3}

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, bankIncomeInsightsCompleted. The remaining callback events are informational and subject to change.

onEvent
linkEvent
LinkEvent
Contains the eventName and metadata for the Link event.
eventName
EventName
An enum representing the event that has just occurred in the Link flow.
bankIncomeInsightsCompleted
The user has completed the Assets and Bank Income Insights 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 exited Link after successfully linking an Item.
identityVerificationStartStep
The user has started a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationPassStep
The user has passed a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationFailStep
The user has failed a step of the Identity Verification flow. The step is indicated by view_name.
identityVerificationReviewStep
The user has reached the pending review state.
identityVerificationCreateSession
The user has started a new Identity Verification session.
identityVerificationResumeSession
The user has resumed an existing Identity Verification session.
identityVerificationPassSession
The user has successfully completed their Identity Verification session.
identityVerificationFailSession
The user has failed their Identity Verification session.
identityVerificationOpenUI
The user has opened the UI of their Identity Verification session.
identityVerificationResumeUI
The user has resumed the UI of their Identity Verification session.
identityVerificationCloseUI
The user has closed the UI of their Identity Verification session.
matchedSelectInstitution
The user selected an institution that was presented as a matched institution. This event can be emitted either during the Returning User Experience flow or if the institution's routing_number was provided when calling /link/token/create. To distinguish between the two scenarios, see metadata.matchReason.
matchedSelectVerifyMethod
The user selected a verification method for a matched institution. This event is emitted only during the Returning User Experience flow.
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.
viewDataTypes
The user has viewed data types on the data transparency consent pane.
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.
metadata
EventMetadata struct
An object containing information about the event
accountNumberMask
Optional<String>
The account number mask extracted from the user-provided account number. If the user-inputted account number is four digits long, account_number_mask is empty. Emitted by SUBMIT_ACCOUNT_NUMBER.
errorCode
Optional<ExitErrorCode>
The error code that the user encountered. Emitted by: error, exit.
errorMessage
Optional<String>
The error message that the user encountered. Emitted by: error, exit.
exitStatus
Optional<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.
institutionID
Optional<InstitutionID> (Optional<String>)
The ID of the selected institution. Emitted by: all events.
institutionName
Optional<String>
The name of the selected institution. Emitted by: all events.
institutionSearchQuery
Optional<String>
The query used to search for institutions. Emitted by: searchInstitution.
matchReason
nullablestring
The reason this institution was matched, which will be either returning_user or routing_number. Emitted by: matchedSelectInstitution.
linkSessionID
String
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.
mfaType
Optional<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
requestID
Optional<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.
routingNumber
Optional<String>
The routing number submitted by user at the micro-deposits routing number pane. Emitted by SUBMIT_ROUTING_NUMBER.
selection
Optional<String>
Either the verification method for a matched institution selected by the user or the Auth Type Select flow type selected by the user. If selection is used to describe selected verification method, then possible values are phoneotp or password; if selection is used to describe the selected Auth Type Select flow, then possible values are flow_type_manual or flow_type_instant. Emitted by: MATCHED_SELECT_VERIFY_METHOD and SELECT_AUTH_TYPE.
timestamp
Date
An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
viewName
Optional<ViewName>
The name of the view that is being transitioned to. Emitted by: transitionView.
acceptTOS
The view showing Terms of Service in the identity verification flow.
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.
dataTransparency
We disclose the data types being shared.
dataTransparencyConsent
We ask the user to consent to the privacy policy and disclose data types being shared.
documentaryVerification
The view requesting document verification in the identity verification flow (configured via "Fallback Settings" in the "Rulesets" section of the template editor).
error
An error has occurred.
exit
Confirming if the user wishes to close Link.
kycCheck
The view representing the "know your customer" step in the identity verification flow.
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.
oauth
The user is informed they will authenticate with the financial institution via OAuth.
recaptcha
The user was presented with a Google reCAPTCHA to verify they are human.
riskCheck
The risk check step in the identity verification flow (configured via "Risk Rules" in the "Rulesets" section of the template editor).
screening
The watchlist screening step in the identity verification flow.
selectAccount
We ask the user to choose an account.
selectAuthType
The user is asked to choose whether to Link instantly or manually (i.e., with micro-deposits).
selectBrand
The user is asked to select 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.
selfieCheck
The view in the identity verification flow which uses the camera to confirm there is real user that matches their ID documents.
uploadDocuments
The user is asked to upload documents (for Income verification).
verifySMS
The SMS verification step in the identity verification flow.
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.
metadataJSON
RawJSONMetadata (String)
Unprocessed metadata, formatted as JSON, sent from Plaid API.
Select Language
Copy
1linkConfiguration.onEvent = { linkEvent in
2 // Optionally handle linkEvent data according to your application's needs
3}

Next steps

Once you've gotten Link working, see Link best practices for recommendations on further improving the Link flow.

Was this helpful?
Developer community
GitHub
GitHub
Stack Overflow
Stack Overflow
YouTube
YouTube
Twitter
Twitter
Discord
Discord