.png)
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 |
|---|---|
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 |
|---|---|
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.
|
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. |
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 |
CODE
| |
Required Parameters |
| Your custom alphanumeric user ID |
|
| |
| The link to the signup form you provided to Payrix during your implementation process. | |
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:
"result": {
"public_token": "public-sandbox-123abc4d-5678-90ef-g1h2-i34jk56lm789"
"metadata": {
"link_session_id": "79e772be-547d-4c9c-8b76-4ac4ed4c441a",
"institution": {
"name": 'Wells Fargo',
"institution_id": 'ins_4'
},
"account": {
"id": 'abCdEfghijKLMn0pqR1StUV3WXYZa4bcDEfGh',
"name": 'Plaid Checking',
"mask": '0000',
"type": 'depository',
"subtype": 'checking',
"verification_status": 'automatically_verified'
},
"account_id": "abCdEfghijKLMn0pqR1StUV3WXYZa4bcDEfGh"
}
Note: The public-sandbox and public-production prefixes for the public_token parameter vary depending on whether you use the Sandbox or Production Payrix environment to create the account linking session for Plaid.
Warning: The Plaid public_token has a time-to-live (TTL) of 30 minutes.
Please ensure that the relevant Payrix API calls are made within 30 minutes of Plaid account linking completion.
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:
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script type="text/javascript">
(function ($) {
const handler = plaid.create({
userId: "ABCD1234",
countryCode: 'US',
redirectURI: 'https://yourWebsite.com/',
onSuccess: (public_token, metadata) => {
$.post('//api.payrix.com/logins', {
publicToken: public_token,
accountToken: metadata.account_id
});
},
onExit: (error, metadata) => {
if (error != null) {
// Handle exit error if needed.
};
},
onEvent: function (eventName, metadata) {
// Handle Plaid events if needed.
}
});
$('#link-button').on('click', function (e) {
handler.open();
});
})(jQuery);
</script>Tip: The above is just one method of mapping the values to the signup form payload. Utilize the code language and process that best suits your workflow.
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:
"accounts": [{
"primary": 1,
"publicToken": "public-sandbox-123abc4d-5678-90ef-g1h2-i34jk56lm789",
"accountToken": "abCdEfghijKLMn0pqR1StUV3WXYZa4bcDEfGh",
"platform": "PLAID"
}],Note: When mapping the Plaid values, you’ll still be required to set the platform parameter to PLAID for the account linking to be successful in the signup form.
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/