Integrating Plaid Link

📘

For using Cybrid's Plaid integration, not acting as your own Plaid Processor.

<https://docs.cybrid.xyz/docs/how-do-i-work-with-cybrid-and-plaid>

Learn how you can drive the Plaid Link SDK

We highly recommend reviewing Plaid Link documentation for up to date integration details. Here is an overview of how to integrate the Plaid Link SDK:

Documentation: <https://plaid.com/docs/link/>

Plaid provides platform specific SDKs including:

• Web
• IOS
• Android
• React Native
• Webview (deprecated and discouraged by Plaid)

📘

Plaid Link is different than the Plaid backend SDK. It provides a front-end UI that allows Customers to authenticate with their external bank accounts institution.

Initializing Plaid Link (Javascript)

const handler = Plaid.create({
  token: 'GENERATED_LINK_TOKEN',
  onSuccess: (public_token, metadata) => {},
  onLoad: () => {},
  onExit: (err, metadata) => {},
  onEvent: (eventName, metadata) => {},
});

Token

1. Create a Workflow: <https://docs.cybrid.xyz/reference/createworkflow>
   1. Cybrid generates a plaid_link_token by calling Plaid. This process is async. After creating the workflow, it will return a guid. Poll on the workflow guid until a plaid_link_token is returned.
2. Pass the plaid_link_token to the Plaid Link SDK during initialization.

onEvent()

1. Subscribe to events during the Plaid Link SDK flow
   1. A list of events are available here: <https://plaid.com/docs/link/web/#onevent> (please see docs for events associated with your specific platform).
   2. Errors are returned as part of the event subscription. These are Plaid errors, not Cybrid errors. A list of Plaid Link SDK errors are available here: <https://plaid.com/docs/link/web/#link-web-onevent-eventName-ERROR>

onSuccess()

1. Subscribe to both the plaid_public_token and metadata returned in the onSuccess() callback during the Plaid Link SDK flow.
   1. A description of the onSuccess() callback is available here: <https://plaid.com/docs/link/web/#onsuccess>
   2. A Customer can only link one account per Workflow Multiple external bank accounts can be created in the Cybrid Platform, however each account requires a unique workflow.
   3. The linked accounts asset should be validated before proceeding to the next step (creating an external bank account). The account asset is not consistently returned via Plaid metadata. It's recommended to confirm with the Customer that the account asset they just authorized via the Plaid Link flow matches the fiat asset that the Customer's bank is configured with. See supported_fiat_account_assets here: <https://docs.cybrid.xyz/reference/createbank>

Sandbox

In the Cybrid Sandbox environment you will see that the generated plaid_link_token initializes the Plaid Link SDK in Sandbox mode. Data passed here does not have to be real PII. You can try a variety of institutions, with and without an OAuth flow.

Verifying an external bank account requires matching data between a Customers PII from a Persona identity verification, and the PII from an external bank account linked by Plaid. See: <https://docs.cybrid.xyz/docs/how-do-i-create-a-bank-account-verification-v2>For Sandbox testing you can seed the default data from a Persona identity verification (i.e. name of "Alexander J Sample" with address "600 California Street, San Francisco, CA, 94109, US") by selecting any institution and using custom_test_user as the username. When performing an external bank account verification this will ensure that the PII associated with the external bank account matches the customers PII, and allows for end-to-end testing of the flow.

Redirect URIs

A redirect URI tells Plaid where to return after authentication with the customers institution.

OAuth flows will need to have redirect URIs configured, and registered with Cybrid for all environments. This includes redirect URIs for Web, Android Package names for Android, and Universal Link for IOS. For more information about Plaid OAuth flows and redirect URIs see: <https://plaid.com/docs/link/oauth/#create-and-register-a-redirect-uri>

Depending on the platform and the Plaid Link SDK you have implemented you may need to reinitialize Plaid Link: <https://plaid.com/docs/link/oauth/#reinitializing-link>

Next Steps

With the plaid_public_token and the metadata (containing an account_id) returned in the onSuccess() callback you can now create an external bank account on the Cybrid Platform.

1. Create an External Bank Account
   1. API reference: <https://docs.cybrid.xyz/reference/createexternalbankaccount>
   2. Guide (section Plaid): <https://docs.cybrid.xyz/docs/how-do-i-create-customer-external-bank-accounts>.

Plaid Link Update Mode

When a link token for an existing external bank account expires re-authentication with the customers financial institution is required. This customer must complete a Plaid Link Update flow where they will re-authenticate. The interval for which a refresh is required can be different between institutions. For more information about update mode see: <https://plaid.com/docs/link/update-mode/>

📘

No transactions can be preformed against an external bank account that requires re-authentication.

An external bank account requires re-authentication if a GET /external_bank_account/{external_bank_account_guid} returns with the following:

{ "state": "refresh_required" }

1. Create a Workflow: <https://docs.cybrid.xyz/reference/createworkflow>
   1. The workflow API needs to be passed the type link_token_update
2. Pass the plaid_link_token to the Plaid Link SDK during initialization.
3. Customer successfully completes the Plaid Link Update workflow
4. Patch the external bank account: <https://docs.cybrid.xyz/reference/patchexternalbankaccount>
   1. The external bank account API needs to be passed the state completed
   2. If the customers external bank account is currently verified the external bank account state will update from refresh_required to completed, if the state is unverified it will remain unverified