You can integrate Plaid with Payrix Pro to streamline and enhance the onboarding experience for Merchants. Linking accounts using the Plaid integration reduces the chances for Merchant input errors that can cause delays in their disbursements.
This guide outlines the steps to use your own Merchant boarding web or app interface with a Plaid integration along with the Payrix Pro Merchant Boarding APIs to create new Merchant bank accounts when the Merchant successfully links with Plaid.
Note
This guide covers the steps to use the Payrix Pro integration with Plaid. Payrix Pro does not support syncing with your external business’s Plaid integrations.
You’ll need to manually add a new bank account for the Merchant using the Payrix Pro portal or using the Payrix Pro 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 Pro 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 Pro Merchant creation flow.
Plaid Link Merchant Flow
The following screenshots show the standard flow that a Merchant will experience when linking their accounts. The specific text and onSuccess and onExit messages are preconfigured 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
Using an easy-to-integrate client-side code snippet, Plaid’s code creates a button that launches the Plaid Link UI when clicked. See Plaid’s documentation for the Link UI for more details.
Plaid Link Configuration Prerequisites
Before getting started with the steps below, ensure you have completed the necessary prerequisites:
Note
The Payrix Pro platform does not support the ability to sync your business’s Plaid Integration (for linking to your platform).
Submit an Partner Services ticket for Product Registration to begin your Plaid integration process 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.
Must be a PNG file under 4 MB at 1024 × 1024 px
End-Customer Technical Contact
The Email, Phone, and Ticket form for your Merchant Support.
First Name
The first name of an owning or managing member of the business.
Last Name
The last name of an owning or managing member of the business.
Email
The email address for the owning or 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 Pro 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 Pro platform and the Plaid integration service. The following are examples of the request and response body for the link token creation API request:
Example Request
POST /plaid/linkToken/create HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api.payrix.com
APIKEY: {apiKey}{
"userId": "ABCD1234",
"countryCode": "US",
"redirectUri": "https://yourWebsite.com"
}Required Parameter | Description |
| Your custom alphanumeric user ID |
|
|
| The link to the signup form you provided to the Payrix Pro team during your implementation process |
Example Response
{
"linkToken": "link-sandbox-123abc4d-5678-90ef-g1h2-i34jk56lm789",
"requestId": "abCdEfghijKLMn0"
}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 OnSuccess Callback 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 that the public-sandbox and public-production prefixes for the public_token parameter vary depending on whether you use the Sandbox or Production Payrix Pro environment to create the account linking session for Plaid.
Important!
The Plaid
public_tokenhas a time-to-live (TTL) of 30 minutes. Ensure that the relevant Payrix Pro 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 the previous step 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. Use 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 Pro 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"
}],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 Pro, 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 Pro 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.
Full Signup Form Page Example
<DOCTYPE html>
<html lang="en-US">
<head>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.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>
</head>
<body>
<h1>Your Signup Form</h1>
...
<button id="link-button">Link Account</button>
...
</body>
</html>Signup form payload example with populated linked Plaid account
{
"resource": "/logins",
"data": {
"username": "test_username",
"password": "test_password",
"roles": 128,
"first": "first",
"middle": "middle",
"last": "last",
"email": "[email protected]",
"address1": "123 Street Ave",
"city": "Miami",
"state": "FL",
"zip": "11111",
"country": "USA",
"phone": "1111111111",
"entities": [
{
"type": 1,
"country": "USA",
"name": "name",
"globalBusinessId": "111111111",
"globalBusinessType": "ssn",
"website": "https://test.com",
"email": "[email protected]",
"merchant": {
"mcc": "0742",
"environment": "cardPresent",
"dba": "dba",
"annualCCSales": "2000",
"avgTicket": "2000",
"saqType": "SAQ-A",
"saqDate": "20211201",
"qsa": "qsa",
"members": [
{
"title": "title",
"first": "first",
"middle": "middle",
"last": "last",
"email": "[email protected]",
"phone": "1111111111",
"dob": "19480101",
"ssn": "111111111",
"significantResponsibility": 1,
"address1": "123 Street Ave",
"address2": "108",
"city": "Miami",
"state": "FL",
"zip": "11111",
"country": "USA",
"primary": 1,
"ownership": 5000
}
],
"tcAttestation": 1,
"new": 0,
"visaDisclosure": 1,
"tmxSessionId": "1abc23d4-567e-8fg9-h0ij-1k2lm34o5678"
},
"customerPhone": "1111111111",
"phone": "1111111111",
"public": 0,
"industry": "industry",
"payoutSecondaryDescriptor": "payoutSe",
"address1": "123 Street Ave",
"address2": "456",
"city": "Miami",
"state": "FL",
"zip": "11111",
"termsAgree": true,
"tcAttestation": true,
"signature": "data:image/png;base64,....",
"accounts": [
{
"primary": 1,
"publicToken": "public-sandbox-123abc4d-5678-90ef-g1h2-i34jk56lm789",
"accountToken": "abCdEfghijKLMn0pqR1StUV3WXYZa4bcDEfGh",
"platform": "PLAID"
}
],
"notes": [
{
"type": "note",
"note": "Custom T&C #1: 1"
}
]
}
]
}
}API Documentation Resources
Plaid API: https://plaid.com/docs/#integrating-with-link
Payrix Pro API: https://portal.payrix.com/docs/api
Plaid OAuth: https://plaid.com/docs/link/oauth/