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.

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: Fetch a Link token

A link_token is a one-time use token that is used to initialize Plaid Link. You can create a link_token and configure it for your specific Link flow by calling the /link/token/create endpoint from your server.

Fetch a Link token

 Copy

    curl -X POST https://sandbox.plaid.com/link/token/create \
    -H 'Content-Type: application/json' \
    -d '{ 
      "client_id": "CLIENT_ID", 
      "secret": "SECRET", 
      "client_name": "My App", 
      "user": { "client_user_id": "UNIQUE_USER_ID" }, 
      "products": ["transactions"], 
      "country_codes": ["US"], 
      "language": "en", 
      "webhook": "https://sample.webhook.com"
    }'
  

    import plaid from 'plaid'
    import express from 'express';

    const app = express();

    const plaidClient = new plaid.Client({
      clientID: PLAID_CLIENT_ID,
      secret: PLAID_SECRET,
      env: PLAID_ENVIRONMENT,
      options: { version: '2019-05-29' },
    })

    app.post('/create_link_token', async function(request, response, next) {
      // 1. Grab the client_user_id by searching for the current user in your database
      const user = await User.find(...);
      const clientUserId = user.id;

      // 2. Create a link_token for the given user
      plaidClient.createLinkToken({ 
        user: { 
          client_user_id: clientUserId,
        },
        client_name: 'My App',
        products: ['transactions'],
        country_codes: ['US'],
        language: 'en',
        webhook: 'https://sample.webhook.com',
      }, (err, res) => {
        const link_token = res.link_token;

        // 3. Send the data to the client
        response.json({ link_token });
      });
    });

    app.listen(3000, function() {
      console.log('server listening on port 3000');
    });
  

    require 'plaid'
    require 'json'
    require 'sinatra'

    client = Plaid::Client.new(env: PLAID_ENVIRONMENT,
                               client_id: PLAID_CLIENT_ID,
                               secret: PLAID_SECRET)

    post '/create_link_token' do
      # 1. Grab the client_user_id by searching for the current user in your database
      current_user = User.find(...)
      client_user_id = current_user.id

      # 2. Create a link_token for the given user
      response = client.link_token.create(
        user: {
          client_user_id: client_user_id
        },
        client_name: 'My App',
        products: ['transactions'],
        country_codes: ['US'],
        language: 'en',
        webhook: 'https://sample.webhook.com',
      )
      link_token = response['link_token']

      # 3. Send the data to the client
      content_type :json
      response.to_json
    end
  

    import plaid
    import json
    from flask import Flask
    from flask import request
    from flask import jsonify

    app = Flask(<strong>name</strong>)

    client = plaid.Client(client_id=PLAID_CLIENT_ID,
                          secret=PLAID_SECRET,
                          environment=PLAID_ENV,
                          api_version='2019-05-29')

    @app.route('/create_link_token')
      # 1. Grab the client_user_id by searching for the current user in your database
      user = User.find(...)
      client_user_id = user.id

      # 2. Create a link_token for the given user
      response = client.LinkToken.create({
        'user': {
          'client_user_id': client_user_id,
        },
        'products': ["transactions"],
        'client_name': "My App",
        'country_codes': ['US'],
        'language': 'en',
        'webhook': 'https://sample.webhook.com',
      })
      link_token = response['link_token']

      # 3. Send the data to the client
      return jsonify(response)

    if __name__ == '__main__':
      app.run(port=3000)
  

    package com.sample.application

    import com.plaid.client.PlaidClient;
    import com.plaid.client.request.LinkTokenCreateRequest;
    import com.plaid.client.request.LinkTokenCreateResponse;
    import java.io.IOException;
    import java.lang.String;
    import java.util.Collections;
    import javax.ws.rs.POST;
    import javax.ws.rs.Path;
    import javax.ws.rs.Produces;
    import javax.ws.rs.core.MediaType;
    import retrofit2.Response;

    @Path("/create_link_token")
    @Produces(Mediatype.APPLICATION_JSON)
    public class LinkTokenResource {
      private PlaidClient plaidClient

      public LinkTokenResource() {
        this.plaidClient = PlaidClient.newBuilder()
          .clientIdAndSecret("CLIENT_ID", "SECRET")
          .sandboxBaseUrl()
          .build();
      }

      @POST
      public LinkTokenCreateResponse getLinkToken() throws IOException {
        // 1. Grab the client_user_id by searching for the current user in your database
        User userFromDB = db.find(...);
        String clientUserId = userFromDB.id;
        LinkTokenCreateRequest.User user = new LinkTokenCreateRequest.User(clientUserId)

        // 2. Create a link_token for the given user
        Response<LinkTokenCreateResponse> response = 
          plaidClient.service()
            .linkTokenCreate(
              new LinkTokenCreateRequest(
                user,
                "My App",
                Collections.singletonList("transactions"),
                Collections.singletonList("US"),
                "en"
              )
              .withWebhook("https://sample.webhook.com")
            ).execute();

        // 3. Send the data to the client
        return response.body();
      }
    }
  

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.

Integrate with Link

 Copy

    <button id="link-button">Link Account</button>
    <script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
    <script type="text/javascript">
    (async function() {
      const fetchLinkToken = async () => {
        const response = await fetch('/create_link_token', { method: 'POST' });
        const responseJSON = await response.json();
        return responseJSON.link_token;
      };

      const configs = {
        // 1. Pass a new link_token to Link.
        token: await fetchLinkToken(),
        onSuccess: async function(public_token, metadata) {
          // 2a. Send the public_token to your app server.
          // The onSuccess function is called when the user has successfully
          // authenticated and selected an account to use.
          await fetch('/get_access_token', { 
            method: 'POST',
            body: JSON.stringify({ public_token: public_token }),
          });
        },
        onExit: async function(err, metadata) {
          // 2b. Gracefully handle the invalid link token error. A link token
          // can become invalidated if it expires, has already been used
          // for a link session, or is associated with too many invalid logins.
          if (err != null && err.error_code === 'INVALID_LINK_TOKEN') {
            linkHandler.destroy();
            linkHandler = Plaid.create({
              ...configs,
              token: await fetchLinkToken(),
            });
          }
          if (err != null) {
            // Handle any other types of errors.
          }
          // 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.
        },
      };

      var linkHandler = Plaid.create(configs);

      document.getElementById('link-button').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.

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

[
  {
    name: 'Bank of America',
    institution_id: 'ins_1',
    auth: true,
    transactions: 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 transactions.

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.

Exchange this public_token for a Plaid access_token using the /item/public_token/exchange API endpoint. You will also send the account_id selected by the user to Plaid. Plaid will automatically create and return a Stripe bank account token for this account, which can 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.

You can create Stripe bank account tokens in all three API environments:

• Sandbox (https://sandbox.plaid.com): test simulated users with Stripe's "test mode" API
• Development (https://development.plaid.com): test live users
• Production (https://production.plaid.com): production environment for when you're ready to go live

 Copy

// Change sandbox to development to test with live users and change
// to production when you're ready to go live!
var plaid = require('plaid');
var plaidClient = new plaid.Client({
    clientID: 'PLAID_CLIENT_ID',
    secret: 'PLAID_SECRET',
    env: plaid.environments.sandbox
});
plaidClient.exchangePublicToken('PUBLIC_TOKEN', function(err, res) {
    var accessToken = res.access_token;
    // Generate a bank account token
    plaidClient.createStripeToken(accessToken, 'ACCOUNT_ID', function(err, res) {
        var bankAccountToken = res.stripe_bank_account_token;
    });
});

# Exchange token
curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
-H 'Content-Type: application/json'
-d '{
  "client_id": "[Plaid Client ID]",
  "secret": "[Plaid secret]",
  "public_token": "[Public token]"
}'

# Create bank account token
curl -X POST https://sandbox.plaid.com/processor/stripe/bank_account_token/create \
-H 'Content-Type: application/json'
-d '{
  "client_id": "[Plaid Client ID]",
  "secret": "[Plaid secret]",
  "access_token": "[Access token]",
  "account_id": "[Account ID]"
}'

# Change sandbox to development to test with live users and change
# to production when you're ready to go live!
client = Plaid::Client.new(env: :sandbox,
                           client_id: PLAID_CLIENT_ID,
                           secret: PLAID_SECRET)

exchange_token_response = client.item.public_token.exchange('[Plaid Link public_token]')
access_token = exchange_response['access_token']

stripe_response = client.processor.stripeBankAccountTokenCreate(access_token, '[Account ID'])
bank_account_token = stripe_response['stripe_bank_account_token']

// Use builder to create a client
PlaidClient plaidClient = PlaidClient.newBuilder()
  .clientIdAndSecret(PLAID_CLIENT_ID, PLAID_SECRET)
  // Use the Sandbox. Can also be
  // developmentBaseUrl() or productionBaseUrl()
  .sandboxBaseUrl()
  .build();

// Required request parameters are always Request object constructor arguments
Response<ItemPublicTokenExchangeResponse> exchangeResponse = plaidClient.service()
    .itemPublicTokenExchange(new ItemPublicTokenExchangeRequest("[Plaid Link public_token]")).execute();

if (exchangeResponse.isSuccessful()) {
  String accessToken = exchangeResponse.body().getAccessToken();
  Response<ItemStripeTokenCreateResponse> stripeResponse =
      client().service().itemStripeTokenCreate(new ItemStripeTokenCreateRequest(accessToken, "[Account ID]")).execute();

  if (stripeResponse.isSuccessful()) {
    String bankAccountToken = stripeResponse.body().getStripeBankAccountToken();
  }
}

# Change sandbox to development to test with live users and change
# to production when you're ready to go live!
client = Client(
    client_id=PLAID_CLIENT_ID,
    secret=PLAID_SECRET,
    environment='sandbox',
    api_version='2019-05-29'  # Specify API version
)
exchange_token_response = client.Item.public_token.exchange('[Plaid Link public_token]')
access_token = exchange_token_response['access_token']

stripe_response = client.Processor.stripeBankAccountTokenCreate(access_token, '[Account ID]'])
bank_account_token = stripe_response['stripe_bank_account_token']
          

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

{
  "stripe_bank_account_token": "btok_5oEetfLzPklE1fwJZ7SG",
  "request_id": "[Unique request ID]"
}

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.

Step 5: Test with sandbox credentials

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

Use Stripe's ACH API in test mode to create test transfers using the bank account tokens you retrieve from Plaid's Sandbox API environment.

Step 6: Get ready for production

Your account is immediately enabled for our Sandbox and Development environments (https://sandbox.plaid.com and https://development.plaid.com), which allows you to test with Sandbox API credentials and up to 100 live users. To move to Production, please request access from the Dashboard.

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.