Plaid Integration Guide for API Partners

Introduction

Payrix has partnered with Plaid to offer the ability to provide merchants with a streamlined onboarding experience.  While this capability is already available on Payrix’s Merchant Sign Up forms, this document will address Payrix Partners who utilize their own boarding UI and thus leverage Payrix’s Merchant Boarding APIs in order to create Merchant accounts.  

Utilizing Plaid’s secure account linking capabilities, merchant boarding can be accelerated yielding higher conversion rates and faster time to be able to process transactions.  Additionally, linking accounts via Plaid reduces the chances for merchant input errors which can cause delays in their disbursements.

Overview

Plaid is the industry leader in providing simple and elegant user experiences around bank account validation and is designed to optimize conversion.  Their UI consists of a merchant-facing front end element as well as a comprehensive backend API suite that Payrix can leverage for Merchant Risk Assessment.

Integrating Plaid offers numerous benefits to the merchant:

• Fast: By prompting the Plaid Link UI in your Merchant Boarding flow merchants can bypass steps requiring the upload of bank statements, voided checks, or other bank validation documentation.

• Easy: Plaid’s UI natively handles any Multi-Factor Authentication (MFA) required by banks and offers industry leading conversion rates.

• Comprehensive: Plaid supports 11,000+ financial institutions in the US, Canada, and Europe.

• Secure: Plaid utilizes industry exceeding standards of security.  Currently, end-to-end AES-256 encryption is utilized to ensure the safety and security of your merchant’s data.  Additionally, Payrix will never have access to the merchant’s banking credentials.

High Level Plaid Implementation Flow Diagram

The flow diagram below depicts the Plaid flow from the Payrix Partner’s perspective.  For the purposes of 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.

Note: The Plaid publicToken has a TTL of 30 minutes.  Please ensure that the relevant Payrix API calls are made within 30 minutes of Plaid account linking.

Plaid Link Merchant Progression Example

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.

Initial Plaid Link Screen

Select Financial Institution Screen

Financial Institution Login Screen

Selecting Bank Account Page

On Successful completion

Plaid Code Examples

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

Plaid Link Code requires 3 items to be configured prior to deployment:

1. Configure clientName: Indicate both Payrix and your entity name

2. Configure env: Utilize sandbox testing, Production is used for linking live bank accounts

3. Configure key: This is retrieved from Implementations or your Relationship Manager.

<button id="link-button">Link Account</button>
<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($) {
  var handler = Plaid.create({
    // follow the below clientName convention
    clientName: 'Plaid Payrix - <partner_name>',
    // Optional, specify an array of ISO-3166-1 alpha-2 country
    // codes to initialize Link; European countries will have GDPR
    // consent panel
    countryCodes: ['US'],
 // Utilize ‘sandbox’ for testing, otherwise utilize ‘production’ for 
    // live site
    env: 'sandbox',
    // Replace with your Plaid Public Key from the Payrix Dashboard
    key: 'PUBLIC_KEY',
    product: ['auth'],
    // Optional, use webhooks to get transaction and error updates
    webhook: 'https://requestb.in',
    // Optional, specify a language to localize Link
    language: 'en',
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
    onExit: function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
      }
      // 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.
    },
    onEvent: function(eventName, metadata) {
      // Optionally capture Link flow events, streamed through
      // this callback as your users connect an Item to Plaid.
      // For example:
      // eventName = "TRANSITION_VIEW"
      // metadata  = {
      //   link_session_id: "123-abc",
      //   mfa_type:        "questions",
      //   timestamp:       "2017-09-14T14:42:19.350Z",
      //   view_name:       "MFA",
      // }
    }
  });

  $('#link-button').on('click', function(e) {
    handler.open();
  });
})(jQuery);
</script>

OnSuccess () Callback:

Retrieve and store the account_id and public_token for use in API call(s) to payrix

data:
account:
  id: "WvPq5vvmr9TqbwPLVrZKSRA5M4DXkAFlyvDQn"
  mask: "0000"
  name: "Plaid Checking"
  subtype: "checking"
  type: "depository"
  __proto__: Object
  account_id: "WvPq5vvmr9TqbwPLVrZKSRA5M4DXkAFlyvDQn"
accounts: Array(1)
0:
  id: "WvPq5vvmr9TqbwPLVrZKSRA5M4DXkAFlyvDQn"
  mask: "0000"
  name: "Plaid Checking"
  subtype: "checking"
  type: "depository"
  __proto__: Object
  length: 1
  __proto__: Array(0)
institution:
  institution_id: "ins_4"
  name: "Wells Fargo"
  __proto__: Object
link_session_id: "1c1143ac-0467-4757-8d08-7f23bff0c8a2"
public_token: "public-sandbox-0dbe2b09-8d4b-4eed-9825-36e7fa36e629"

Example Merchant Boarding Form from Payrix Boarding Form:

Payrix API Examples

The below examples depict the changes to the API call based on the Plaid onSuccess() callback.  For onExit() callbacks, there is no change to your existing API Merchant Creation flow.

Variable Mapping:

Example Payrix API call to Accounts resource:

"accounts": { 
    "platform": "PLAID",
    "primary": 1, 
    "publicToken": "public-sandbox-51a72326-ca8d-4065-ac1f-409c26a608d9", 
    accountToken: "a5wlGbyKbgC5w9Dd9BPlUN1avQJojyi757Nd6", 
    "type": "all"
 }

Resources

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

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

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