Introduction

Plaid and Stripe have partnered to offer frictionless money transfers without the need to ever handle an account or routing number. Use Plaid Link to instantly authenticate your customer's account and automatically generate a Stripe bank account token so that you can accept ACH payments via their ACH API.

This guide is designed for those who already have a ACH-enabled account at both Stripe and Plaid. If that's not you, head over to the Stripe ACH docs to get started. You'll be able to sign up for a Plaid account from there.

Try out the demo

Getting Started

You'll first want to familiarize yourself with Plaid Link, a drop-in integration for the Plaid API that handles input validation, error handling, and multi-factor authentication.

Your customers will use Link to authenticate with their financial institution and select the depository account they wish to use for ACH transactions. From there, you'll receive a Plaid access_token, allowing you to leverage real-time balance checks and transaction data, and a Stripe bank_account_token, which allows you to move money via Stripe's ACH API without ever handling an account or routing number.

Instructions

Step 1: Set up your Plaid and Stripe accounts

You'll need accounts at both Plaid and Stripe in order to use the Plaid Link + Stripe integration. You'll also need to connect your Plaid and Stripe accounts so that Plaid can facilitate the creation of bank account tokens on your behalf.

First, sign up for a Stripe account if you do not already have one and then verify that it is enabled for ACH access. To verify that your Stripe account is ACH enabled, head to the ACH Guide when you are logged in to your Stripe account. If you see:

your account is not enabled. Click 'Accept Terms of Service' to enable your Stripe account for ACH. If you do not see the 'Accept Terms of Service' button, your Stripe account is already enabled for ACH access and you do not need to take any action.

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

If you already have a Plaid account, please contact our support team to enable your account.

To verify that your Plaid account is enabled for the integration, go to the Integrations section of the account dashboard. If you see:

your Plaid account is enabled for the integration but you have not connected your Stripe account.

Click the 'Connect With Stripe' button to connect your Plaid and Stripe accounts. This step is required so that Plaid can facilitate the creation of Stripe bank account tokens on your behalf.

Once your Stripe account is connected, you'll see:

Your Plaid account is now set up for the integration!

Step 2: Get your public_key

Your public_key is available from the Plaid Dashboard:

Your public_key is a less privileged version of your client_id and secret. It simply associates accounts you create using Plaid Link with your client_id. All Plaid API requests must be made using your private client_id and secret.

Step 3: Integrate with Plaid Link

Integrating with Link is easy. All it takes is a few lines of client-side JavaScript and a small server-side handler to exchange the Link public token for a Plaid access token and a Stripe bank account token.

You can either trigger the "Institution Select" view, a general purpose view that lists all Plaid-supported institutions, or trigger a particular institution's login form. See below:


<button id='linkButton'>Open Link - Institution Select</button>
<button id='bofaButton'>Open Link - Bank of America</button>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script&gt;
<script>
var linkHandler = Plaid.create({
  selectAccount: true,
  env: 'tartan',
  clientName: 'Client Name',
  key: '[YOUR PUBLIC_KEY]',
  product: 'auth',
  onLoad: function() {
    // The Link module finished loading.
  },
  onSuccess: function(public_token, metadata) {
    // The onSuccess function is called when the user has successfully
    // authenticated and selected an account to use.
    //
    // When called, you will send the public_token and the selected
    // account ID, metadata.account_id, to your backend app server.
    //
    // sendDataToBackendServer({
    //   public_token: public_token,
    //   account_id: metadata.account_id
    // });
    console.log('Public Token: ' + public_token);
    console.log('Customer-selected account ID: ' + metadata.account_id);
  },
  onExit: function(err, metadata) {
    // The user exited the Link flow.
    if (err != null) {
      // The user encountered a Plaid API error prior to exiting.
    }
    // metadata contains information about the institution
    // that the user selected and the most recent API request IDs.
    // Storing this information can be helpful for support.
  },
});

// Trigger the Bank of America login view directly
document.getElementById('bofaButton').onclick = function() {
  linkHandler.open('bofa');
};

// Trigger the standard Institution Select view
document.getElementById('linkButton').onclick = function() {
  linkHandler.open();
};
</script>

See the parameter reference for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with one function, open, and one property, institutions. open accepts either no arguments or an optional [institution ID][institutions-docs]. If no argument is provided, the "Institution Select" view is opened. If a valid institution ID is provided, the login form for that particular institution is opened.

The exposed institutions property is an Array of Objects in the form:


[{name: 'Bank of America', type: 'bofa', auth: true, connect: true},
 ...]

The institutions property will be populated with all supported institutions for a given product. That is, the list of institutions will be different for auth and connect. Use the institutions property to dynamically generate a list of supported institutions for your Link integration - by doing so, your app will support new institutions and products automatically.

Step 4: 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 account_id (a property on the metadata object) via the onSuccess callback.

This public_token must be exchanged for a Plaid access_token using the /exchange_token API endpoint. You will also send the account_id selected by the user to the /exchange_token endpoint. Plaid will automatically create and return a Stripe bank account token for this account, which can be then be used to move money via Stripe's ACH API. The bank account token will be linked to the Stripe account you linked in your Plaid Dashboard.

/exchange_token endpoint

The /exchange_token endpoint is available in both the tartan (https://tartan.plaid.com) and production (https://api.plaid.com) environments.

Method Endpoint Required Parameters
POST /exchange_token client_id, secret, public_token, account_id

The /exchange_token endpoint is integrated into the plaid-node, plaid-go, plaid-ruby, and plaid-python, and plaid-java client libraries.

If you are working with a library that does not yet support the /exchange_token endpoint you can simply make a standard HTTPS request:


curl -X POST https://tartan.plaid.com/exchange_token \
>   -d client_id="$plaid_client_id" \
>   -d secret="$plaid_secret" \
>   -d public_token="$public_token_from_plaid_link_module" \
>   -d account_id="$account_id_from_plaid_link_module"

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


{
  "access_token": "foobar_plaid_access_token",
  "stripe_bank_account_token": "foobar_stripe_bank_account_token"
}

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

Note: The account_id parameter is required if you wish to receive a Stripe bank account token. If the account_id parameter is omitted, no bank account token will be generated. Only the access_token will be returned.

Sample server-side handler

Below is a sample server-side handler using Express and the plaid-node library:


var express = require('express');
var plaid = require('plaid');

var app = express();

var plaidClient = new plaid.Client(process.env.PLAID_CLIENT_ID,
                                   process.env.PLAID_SECRET,
                                   plaid.environments.tartan);

// /authenticate accepts the public_token and account_id from Link
app.post('/authenticate', function(serverReq, serverRes) {
  var public_token = serverReq.body.public_token;
  var account_id = serverReq.body.account_id;

  // Exchange a public_token and account_id for a Plaid access_token
  // and a Stripe bank account token
  plaidClient.exchangeToken(public_token, account_id, function(err, res) {
    if (err != null) {
      // Handle error!
    } else {
      // This is your Plaid access token - store somewhere persistent
      // The access_token can be used to make Plaid API calls to
      // retrieve accounts and transactions
      var access_token = res.access_token;

      // This is your Stripe bank account token - store somewhere
      // persistent. The token can be used to move money via
      // Stripe's ACH API.
      var bank_account_token = res.stripe_bank_account_token;
    }
  });
});

Step 5: Test with sandbox credentials

Link's sandbox mode is compatible with Plaid's sandbox API and Stripe's "test mode" API. To test the integration in sandbox mode, simply use the Plaid sandbox credentials along with your public_key.

Use Stripe's ACH API in test mode to create test transfers using the bank account token you retrieve from the /exchange_token endpoint.

Step 6: Get ready for production

Your account is immediately enabled for our development environment (https://tartan.plaid.com), which allows you to test with sandbox API credentials and up to 100 live bank accounts. To enable production access, please drop us a note.

Support and questions

Find answers to many common integration questions and concerns—such as pricing, sandbox and test mode usage, and more—at our Help Center and 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.