Plaid logo
Docs
ALL DOCS

Identity

  • Introduction to Identity
  • Add Identity to your app
  • Identity Document Upload
  • Identity partners
    • Alloy
Plaid logo
Docs
Close search modal
Ask Bill!
Ask Bill!
Hi! I'm Bill! You can ask me all about the Plaid API. Try asking questions like:
  • What's the difference between an Item and an access token?
  • Why is /transactions/sync/ better than /get?
  • What is Remember Me?
Note: Bill isn't perfect. He's just a robot platypus that reads our docs for fun. You should treat his answers with the same healthy skepticism you might treat any other answer on the internet. This chat may be logged for quality and training purposes. Please don't send Bill any PII -- he's scared of intimacy. All chats with Bill are subject to Plaid's Privacy Policy.
Plaid.com
Log in
Get API Keys
Open nav

Add Alloy to your app

Instantly authenticate your customers' bank accounts with Alloy's API and third-party data sources

Partnership Alloy logo

Overview

Plaid and Alloy have partnered to offer identity data orchestration and credit decisioning to financial services companies looking to address fraud and uphold compliance. Plaid enables consumers to instantly and securely authenticate their identity associated with their bank account, including address, email, phone number, and name. Merchants can leverage Plaid Identity along with Alloy to pull third-party data and verify consumer identity at account opening, lending application review and on an ongoing basis.

This guide covers partnering with Alloy for account ownership verification. To learn about integrating with Alloy for underwriting, see Assets Partnerships: Alloy.

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in client-side integration for the Plaid API that handles input validation, error handling, and multi-factor authentication. You will also need to have a verified Alloy account to add a bank funding source. Your customers will use Link to authenticate with their financial institution and select the bank account they wish to connect. From there, you'll receive a Plaid access_token and a Alloy processor_token, which allows you to quickly and securely retrieve the user's financial data via Alloy's API. Utilizing Plaid + Alloy enables a seamless workflow for connecting external financial accounts to Alloy.

Instructions

Set up your accounts

You'll need accounts at both Plaid and Alloy in order to use the Plaid + Alloy integration. You'll also need to enable your Plaid account for the Alloy integration.

First, you will need to work with the Alloy team to sign up for a Alloy account, if you do not already have one.

Next, verify that your Plaid account is enabled for the integration. If you do not have a Plaid account, create one.

To enable your Plaid account for the integration, go to the Integrations section of the account dashboard. If the integration is off, simply click the 'Enable' button for Alloy to enable the integration.

You'll need to complete your Plaid Application Profile in the Dashboard, which involves filling out basic information about your app, such as your company name and website. This step helps your end-users learn more how your product uses their bank information and is also required for connecting to some banks.

Finally, you'll need to go to the Data Transparency section of the Link customization UI and pick the use cases that you will be using Alloy to power, so that Plaid can request the appropriate authorization and consent from your end users. If you have any questions, contact Alloy.

Create a link_token

In order to integrate with Plaid Link, you will first need to create a link_token. A link_token is a short-lived, one-time use token that is used to authenticate your app with Link. To create one, make a /link/token/create request with your client_id, secret, and a few other required parameters from your app server. For a full list of link_token configurations, see /link/token/create.

To see your client_id and secret, visit the Plaid Dashboard.

Select Language
1const request: LinkTokenCreateRequest = {
2 user: {
3 client_user_id: 'user-id',
4 phone_number: '+1 415 555 0123'
5 },
6 client_name: 'Wonderwallet',
7 products: ['identity'],
8 country_codes: ['US'],
9 language: 'en',
10 webhook: 'https://sample-web-hook.com',
11 redirect_uri: 'https://domainname.com/oauth-page.html'
12};
13try {
14 const response = await plaidClient.linkTokenCreate(request);
15 const linkToken = response.data.link_token;
16} catch (error) {
17 // handle error
18}
Integrate with Plaid Link

Once you have a link_token, all it takes is a few lines of client-side JavaScript to launch Link. Then, in the onSuccess callback, you can call a simple server-side handler to exchange the Link public_token for a Plaid access_token and a Alloy processor_token.

1<button id="linkButton">Open Link - Institution Select</button>
2<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
3<script>
4 (async function(){
5 var linkHandler = Plaid.create({
6 // Make a request to your server to fetch a new link_token.
7 token: (await $.post('/create_link_token')).link_token,
8 onSuccess: function(public_token, metadata) {
9 // The onSuccess function is called when the user has successfully
10 // authenticated and selected an account to use.
11 //
12 // When called, you will send the public_token and the selected accounts,
13 // metadata.accounts, to your backend app server.
14 sendDataToBackendServer({
15 public_token: public_token,
16 accounts: metadata.accounts
17 });
18 },
19 onExit: function(err, metadata) {
20 // The user exited the Link flow.
21 if (err != null) {
22 // The user encountered a Plaid API error prior to exiting.
23 }
24 // metadata contains information about the institution
25 // that the user selected and the most recent API request IDs.
26 // Storing this information can be helpful for support.
27 },
28 });
29 })();
30
31 // Trigger the authentication view
32 document.getElementById('linkButton').onclick = function() {
33 // Link will automatically detect the institution ID
34 // associated with the public token and present the
35 // credential view to your user.
36 linkHandler.open();
37 };
38</script>

See the Link parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will display the "Institution Select" view, calling exit will close Link, and calling destroy will clean up the iframe.

Write server-side handler

The Link module handles the entire onboarding flow securely and quickly, but does not actually retrieve account data for a user. Instead, the Link module returns a public_token and an accounts array, which is a property on the metadata object, via the onSuccess callback. Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint.

The accounts array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. The `accounts` array will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. In most cases, you will want your users to connect all of their accounts so that they can be tracked in Alloy.

Once you have identified the account you will use, you will send the access_token and account_id property of the account to Plaid via the /processor/token/create endpoint in order to create a Alloy processor_token. You'll send this token to Alloy and they will use it to securely retrieve account details from Plaid.

You can create Alloy processor_tokens in both API environments:

  • Sandbox (https://sandbox.plaid.com): test simulated users
  • Production (https://production.plaid.com): production environment for when you're ready to go live and have valid Alloy Production credentials
Select Language
1const {
2 Configuration,
3 PlaidApi,
4 PlaidEnvironments,
5 ProcessorTokenCreateRequest,
6} = require('plaid');
7
8// Change sandbox to production when you're ready to go live!
9const configuration = new Configuration({
10 basePath: PlaidEnvironments[process.env.PLAID_ENV],
11 baseOptions: {
12 headers: {
13 'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
14 'PLAID-SECRET': process.env.PLAID_SECRET,
15 'Plaid-Version': '2020-09-14',
16 },
17 },
18});
19
20const plaidClient = new PlaidApi(configuration);
21
22try {
23 // Exchange the public_token from Plaid Link for an access token.
24 const tokenResponse = await plaidClient.itemPublicTokenExchange({
25 public_token: publicToken,
26 });
27 const accessToken = tokenResponse.data.access_token;
28
29 // Create a processor token for a specific account id.
30 const request: ProcessorTokenCreateRequest = {
31 access_token: accessToken,
32 account_id: accountID,
33 processor: 'alloy',
34 };
35 const processorTokenResponse = await plaidClient.processorTokenCreate(
36 request,
37 );
38 const processorToken = processorTokenResponse.data.processor_token;
39} catch (error) {
40 // handle error
41}

For a valid request, the API will return a JSON response similar to:

1{
2 "processor_token": "processor-sandbox-0asd1-a92nc",
3 "request_id": "m8MDnv9okwxFNBV"
4}

For possible error codes, see the full listing of Plaid error codes.

Launching to Production

Test with Sandbox credentials

To test the integration in Sandbox mode, simply use the Plaid Sandbox credentials along when launching Link with a link_token created in the Sandbox environment.

When testing in the Sandbox, you have the option to use the /sandbox/public_token/create endpoint instead of the end-to-end Link flow to create a public_token. When using the /sandbox/public_token/create-based flow, the Account Select flow will be bypassed and the accounts array will not be populated. On Sandbox, instead of using the accounts array, you can call /accounts/get and test with any returned account ID associated with an account with the subtype checking or savings.

Get ready for production

Your account is immediately enabled for our Sandbox environment (https://sandbox.plaid.com). To move to Production, please request access from the Dashboard. You will need Alloy Production credentials prior to initiating live traffic in the Alloy API with Plaid.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more, in our docs.

If you're still stuck, open a support ticket with information describing the issue that you're experiencing and we'll get back to you as soon as we can.

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