Add Ocrolus to your app

Plaid and Ocrolus have partnered to offer lenders an easier way to access bank data to make informed loan decisions. Plaid enables businesses to instantly connect a customer's bank account, giving them the ability to authenticate and retrieve account details directly from the financial institution. Ocrolus digitizes bank and credit card statements from all US financial institutions to help lenders digitize their data collection for cash-flow analysis.

With the Plaid + Ocrolus integration, your users can verify their accounts in seconds by inputting their banking credentials in Plaid’s front-end module. Plaid will retrieve the relevant bank information and pass it to Ocrolus for further digestion and reporting in a seamless, secure fashion. Plaid’s mobile-friendly module handles input validation, error handling, and multi-factor authentication, providing a seamless onboarding experience to convert more users for your business.

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. You will also need to create or be an existing Ocrolus customer in order to add a bank account.

Your customers will use Link to authenticate with their financial institution and select the bank account they wish to use for payment and verification of assets. From there, you'll receive a Plaid access_token, which you can use generate an Ocrolus processor_token and/or audit_copy_token, depending on your use case, which allow you to quickly and securely verify banking information via the Ocrolus API without having to store that sensitive information yourself.

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

First, you will need to work with the Ocrolus team to sign up for an Ocrolus 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. 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 the integration is off, simply click the 'Enable' button for Ocrolus to enable the integration.

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. View the documentation for a full list of link_token configurations.

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

1app.post('/api/create_link_token', async function (request, response) {
2  // Get the client_user_id by searching for the current user
3  const user = await User.find(...);
4  const clientUserId = user.id;
5  const request = {
6    user: {
7      // This should correspond to a unique id for the current user.
8      client_user_id: clientUserId,
9    },
10    client_name: 'Plaid Test App',
11    products: ['auth'],
12    language: 'en',
13    webhook: 'https://webhook.example.com',
14    redirect_uri: 'https://domainname.com/oauth-page.html',
15    country_codes: ['US'],
16  };
17  try {
18    const createTokenResponse = await client.linkTokenCreate(request);
19    response.json(createTokenResponse.data);
20  } catch (error) {
21    // handle error
22  }
23});

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 Ocrolus 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      onLoad: function() {
9          // The Link module finished loading.
10      },
11      onSuccess: function(public_token, metadata) {
12        // The onSuccess function is called when the user has
13        // successfully authenticated and selected an account to
14        // use.
15        //
16        // When called, you will send the public_token
17        // and the selected account ID, metadata.account_id,
18        // to your backend app server.
19        //
20        // sendDataToBackendServer({
21        //   public_token: public_token,
22        //   account_id: metadata.account_id
23        // });
24        console.log('Public Token: ' + public_token);
25        console.log('Customer-selected account ID: ' + metadata.account_id);
26      },
27      onExit: function(err, metadata) {
28        // The user exited the Link flow.
29        if (err != null) {
30            // The user encountered a Plaid API error
31            // prior to exiting.
32        }
33        // metadata contains information about the institution
34        // that the user selected and the most recent
35        // API request IDs.
36        // Storing this information can be helpful for support.
37      },
38    });
39  })();
40
41  // Trigger the authentication view
42  document.getElementById('linkButton').onclick = function() {
43    linkHandler.open();
44  };
45</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.

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.

Once you have the access_token for the Item, you can create an Ocrolus processor_token and/or audit_copy_token. You'll send these tokens to Ocrolus and they will use them to securely retrieve banking information from Plaid.

1const { Configuration, PlaidApi, PlaidEnvironments, ProcessorTokenCreateRequest, AssetReportAuditCopyCreateRequest } = require('plaid');
2// Change sandbox to development to test with live users;
3// Change to production when you're ready to go live!
4const configuration = new Configuration({
5  basePath: PlaidEnvironments[process.env.PLAID_ENV],
6  baseOptions: {
7    headers: {
8      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
9      'PLAID-SECRET': process.env.PLAID_SECRET,
10      'Plaid-Version': '2020-09-14',
11    },
12  },
13});
14
15const plaidClient = new PlaidApi(configuration);
16
17try {
18  // Exchange the public_token from Plaid Link for an access token.
19  const tokenResponse = await plaidClient.itemPublicTokenExchange({
20    public_token: PUBLIC_TOKEN,
21  });
22  const accessToken = tokenResponse.access_token;
23
24  // Create a processor token for a specific account id.
25  const request: ProcessorTokenCreateRequest = {
26    access_token: accessToken,
27    account_id: accountID,
28    processor: 'ocrolus',
29  };
30  const processorTokenResponse = await plaidClient.processorTokenCreate(
31    request,
32  );
33  const processorToken = processorTokenResponse.processor_token;
34
35  // Create an Asset Report for the specific access token.
36  const request: AssetReportCreateRequest = {
37    access_tokens: [accessToken],
38    days_requested: 60,
39    options: {},
40  };
41  const response = await plaidClient.assetReportCreate(request);
42  const assetReportId = response.data.asset_report_id;
43  const assetReportToken = response.data.asset_report_token;
44
45  // Create an audit copy token for the Asset Report.
46  const request: AssetReportAuditCopyCreateRequest = {
47    asset_report_token: createResponse.data.asset_report_token,
48    auditor_id: 'ocrolus',
49  };
50  const response = await plaidClient.assetReportAuditCopyCreate(request);
51  const auditCopyToken = response.data.audit_copy_token;
52} catch (error) {
53  // handle error
54}

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

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

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

1{
2  "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
3  "request_id": "UNIQUE_REQUEST_ID"
4}

For more information on creating Asset Report audit_copy_tokens, see the documentation for the Assets product.

You can create Ocrolus processor_tokens in Sandbox (sandbox.plaid.com, allows testing with simulated users). To test the integration in Sandbox mode, use the Plaid Sandbox credentials when launching Link with a link_token created in the Sandbox environment.

To move to Development (a free environment that allows limited access with real users) or Production, request access from the Dashboard. You will want to ensure that you have valid Ocrolus Production credentials prior to connecting bank accounts in the Ocrolus API with Plaid.

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.