Plaid Integration Guide

Payrix has partnered with Plaid to offer the ability to provide Merchants with a streamlined onboarding experience. Linking accounts using the Plaid integration reduces the chances for Merchant input errors which can cause delays in their disbursements.

This guide will outline the steps to utilize your own Merchant boarding web or app interface with a Plaid integration alongside the Payrix Merchant Boarding APIs to create new Merchant bank accounts when the Merchant successfully links with Plaid.

Warning: This guide covers the steps to utilize the Payrix integration with Plaid. Payrix does not currently support syncing with your external business’s Plaid integrations.

You’ll need to manually add a new bank account for the Merchant with Payrix (using the Portal or using the API) providing the account number and routing number like normal.

Plaid Implementation Flow Diagram

The flow diagram below depicts the Plaid flow from the Payrix Partner’s perspective. For this document, only onSuccess() examples are provided. The flow for onExit(), where the Merchant is unable to successfully link their bank account, does not deviate from the standard Payrix Merchant creation flow.

Plaid Link Merchant Flow

The below screenshots show the standard flow that a Merchant will experience when linking their accounts. The specific text and onSuccess and onExit messages are configured by Payrix and no work needs to be done by the Partner in the Plaid client-side code.

Account Link Merchant UI Page	Screenshot Example

Account Link Merchant UI Page	Screenshot Example
Initial Plaid Link Screen
Select Financial Institution Screen
Financial Institution Login Screen
Selecting Bank Account Page
On Successful completion

Tip: Utilizing an easy to integrate client-side code snippet, Plaid’s code creates a button that launches the Plaid Link UI when clicked. Plaid’s documentation for the Link UI can be found here: https://plaid.com/docs/#integrating-with-link

Plaid Link Configuration Prerequisites

Before getting started with the steps below, ensure you have completed the necessary prerequisites:

Warning: Payrix does not currently support the ability to sync your business' Plaid Integration (for linking to your platform) to the Payrix implementation.

Submit an Plaid Integration Ticket with the following information:

Required Info	Description

Required Info	Description
Company name	Your company’s name as known by your Merchants (can be a DBA).
Company Legal Entity name	Your company’s official legal name as filed with your local business and tax regulatory bodies.
Website	Your company’s primary website URL.
Legal Address	The legal mailing address for your company.
Icon	Your company’s logo or other identifying icon. Must be a PNG file under 4MB at 1024 x 1024 px
End-Customer Technical Contact	The Email, Phone, and Ticket form for your Merchant Support.
First Name	The first name of an owning/managing member of the business.
Last Name	The last name of an owning/managing member of the business.
Email	The email address for the owning/managing member above.
Redirect URI	The preferred URI that the Merchant will redirect to after a success or failure of the Plaid account integration: Example: https://test.ThisCompany.com/

Receive confirmation that your account and redirect URI have been successfully added to the Plaid integration by the Payrix Implementations team.

After completing these prerequisites, you’ll be able to proceed to the Plaid Link Configuration steps below.

Plaid Link Configuration

Plaid Link Configuration requires a three-step process:

Plaid Link Initialization Script
Embed the Plaid Link Initialization script into your signup form page file.
Create a Plaid Link Token
Generate a Plaid Link Token to securely establish a connection with the Plaid service.
Map the Plaid Integration Responses
Ensure a smooth integration by mapping the successful Plaid integration response to your Signup Form payload.

Follow each of the steps below to integrate Plaid into your signup form.

1. Add Plaid Link Initialization Script

In your page header, add the following Javascript file from Plaid:

<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>

2. Create a Plaid Link Token

Once created, you must execute an API request to the endpoint below to create a link token, authorizing the secure connection between the Payrix platform and the Plaid integration service.

Request URL & Headers	`POST api.payrix.com/plaid/linkToken/create HTTP/1.1 Accept: application/json Content-Type: application/json Host: api.payrix.com APIKEY: {Payrix API Key}`
Required Parameters	`userId`	Your custom alphanumeric user ID
	`countryCode`	`US` for the United States, `CA` for Canada.
	`redirectURI`	The link to the signup form you provided to Payrix during your implementation process.

Example Request Body

{
  "userId": "ABCD1234",
  "countryCode": "US",
  "redirectUri": "https://yourWebsite.com" 
}

Example Response

Result: The Plaid Link Token will initiate the secure connection to Plaid services and launch the Plaid account link lightbox when initiated by the Merchant clicking the “Link Account” button on your page:

The applying Merchant will complete the Plaid account link form presented on your webpage/UI. When the Merchant successfully signs in with their bank credentials to link their account through Plaid, The Plaid integration will produce a completion page and an onSuccess callback with the following response body:

Plaid OnSuccessCallback Response Example:

3. Create a Handler to Map Plaid `onSuccess` Values to the Signup Form

Add the following scripts to your signup form page, replacing the Required Parameters mentioned in Step 2 with your valid values:

Result: The mapping function defined above will map the public_token from the onSuccess callback response to publicToken on the Payrix Signup Form payload being submitted Merchants (under the "accounts" object array), as well as account_id to accountToken:

Example of Completed Mapping of Plaid onSuccess Values:

Conclusion

After creating a Plaid Link Token through Payrix, successfully adding the Plaid initialization function to your signup page, and integrating the Plaid onSuccess parameter value mapping function, your new Merchants can now link their bank accounts through Plaid directly from your signup form to be used on the Payrix Platform.

See the examples below for a quick recap on the signup form page with all required functionality, and how it appears on an API-submitted signup form.

API Documentation Resources

Plaid API: https://plaid.com/docs/#integrating-with-link

Payrix API: https://portal.payrix.com/docs/api

Plaid OAuth: https://plaid.com/docs/link/oauth/