Instant Account Verification - Plaid Integration

Table of Contents

  • Overview
  • Integration Details
  • Troubleshooting and Support

    • Overview

    There are three parties involved in an ACH transfer with Plaid account verification: the client, Plaid, and SVB. Clients will sign up for API keys with Plaid and will use the Plaid Link front-end component to authenticate an end-user to their financial institution. Once authenticated, Plaid Link will return a public token that the client will exchange for a long-lived access token. Once obtained, that access token can be used to generate a processor token to be passed to SVB. More information about Plaid Link can be found in the Plaid documentation. Processor tokens are processor specific and will be supplied to SVB within the ACH transfer request.

    plaid diagram

     

    Below steps outline the flow of activities to perform an ACH transfer that uses Plaid authentication:

    STEP ACTORS ACTIVITY
    1 SVB Client <-> Plaid   SVB client verifies customer account information with Plaid, and in response receives a temporary public_token.
    2 SVB Client <-> Plaid   SVB client uses the public_token to retrieve the permanent access_token from Plaid.
    3 SVB Client <-> Plaid   SVB client sends the access_token, account ID, and the processor (as “svb_api”) to Plaid. Plaid will respond back with a processor_token.

      The processor_token allows SVB to retrieve account information for the ACH transfer.
    4 SVB Client <-> SVB   SVB client initiates ACH transfer with the processor_token, using the "receiver_verification_details" object instead of receiver account and routing numbers. 

     

     

     

     

     

     

     

     

     

     

    Once the client supplies their processor_token, SVB contacts Plaid with the processor_token and retrieves receiver account and routing numbers. 

    Integration Details

    Before a client can engage with SVB and provide the ACH transfer request, the client will need to retrieve the processor_token from Plaid. Series of events for an SVB client to perform an ACH transfer with Plaid account verification are broken into two main steps:

    1. Plaid integration to receive processor_token
    2. SVB ACH transfer request with processor_token
       

    Step 1 : Plaid integration to receive processor_token

    Clients will need to confirm that:

    • They are registered with Plaid (if not registered, refer to Plaid for a new account)
    • They are registered with SVB to use ACH API with Plaid integration
    • SVB is configured as a processor on their Plaid account

    Once registered, clients can use Plaid Link to allow their customers to link their online banking account. Plaid Link is a client-side module that authenticates and validates a user's credentials with a financial institution.

    Clients will start by creating a link_token, which is required to initiate Plaid Link. After Plaid responds with a link_token, the client can then use the token to launch the Plaid Link UI for the customer.

    Once rendered, Plaid Link lets the end-user choose their financial institution and authenticate:

     

    Imagenjzbr

     

    After a successful link, the SVB client will receive a temporary public_token. Clients can then submit another request to Plaid to exchange the public_token for a long-lived access_token. As the final step, the client will need to send a request to Plaid with both the Plaid account_id and access_token and generate an associated processor_token.

    Below table includes hyperlinks to redirect to Plaid reference documentation for each individual step:
     

    STEP ACTION DESCRIPTION
           1  Create a Plaid Link_token to   generate the Plaid Link widget.  Client will need to perform a server-side call to retrieve a link_token,   which is required to initiate Plaid Link.
           2  Once Plaid Link is initialized and   the end-user has successfully   authenticated, client will receive   a temporary public_token.  Temporary public_token received from this step will be exchanged for a   permanent access_token on step 3.
           3  Exchange public_token for an   access_token.  Once public_token is exchanged, retrieved access_token will be used to   obtain a processor_token.
           4  Using the access_token, and SVB   as processor, create the   processor_token.  Generating the processor_token is the last step before submitting an   SVB ACH transfer request.

     

     

    Step 2 : Submitting the ACH transfer request with processor_token

    The only difference in submitting an ACH transfer with a Plaid processor_token is the updated request body. In case of Plaid verification, receiver account information fields will not be included in the request body, instead the "processor_token" and "provider" fields will be included in the "receiver_verification_details" object. 

    Parameters:
     

    NAME TYPE DESCRIPTION
     account_number

                              required

    		  string  SVB bank account number originating the ACH transfer.

     If testing on sandbox use the account number '1111111111'.

     amount

                              
                                    required

    		  int  Amount of money to transfer, specified in cents.

     Example: To pass in $10.55, use "1055" as the amount. No decimals should be used to represent amount. 
     currency  enum("usd")  If not provided, defaults to "USD".
     

     direction

                              required
     

    		  enum(“credit”, “debit”)  Direction of the transfer.
     effective_date  date  Date when the transfer should take place. Defaults to tomorrow’s date.
     memo  string  Optional 15 digit alphanumeric string that can be used to pass data to the recipient bank.  Examples: an invoice number or transaction reference number.
     metadata  object  Optional metadata to associate with the API resource.

     receiver_name

                              required
     

    		  string  Name of the receiver account holder.
     receiver_verification_details

                              required

    		  object  This object contains encompasses two fields

     processor_token : Plaid processor token
     provider: value will be set to "Plaid" for all Plaid verified ACH transfer requests.

     sec_code

                              required
     

    		  enum(“ccd”, “ppd”, “web”)  SEC code to be used for the ACH transfer.
     service  enum(“standard”, “same-   day”)  Service level. Defaults to standard service.

     

    Sample Postman Request and Response

    Below is a sample Postman request for an ACH transfer submitted to SVB using Plaid processor_token: 

    Postman body request

     

    Sample Postman response:
     

    final plaid response

     

     

     

    Troubleshooting and Support

    SVB provides the below error responses to help troubleshoot integration issues.

     

    SOURCE ERROR DESCRIPTION
                 SVB  Parameter account_number { } must be a valid SVB account number that has been configured for ACH access  No IAV permission - SVB originator account number must be valid and configured for ACH with Plaid verification
                Plaid  The processor is invalid.  This error is encountered when the processor specified to Plaid is not “svb_api”.
                 SVB  Processor token is required for Plaid provider  Missing processor token - Processor token is required when the specified provider is Plaid
                 SVB  Missing required parameter: provider  Missing validator failure – Validator is required when the processor token is supplied,
                 SVB  IAV fields conflicting with receiver or counterparty_id fields  IAV Validation – Multiple receiver fields error, request body includes both receiver account information (and/or   counterparty information) along with processor token
                 SVB  Parameter provider { } must be one of: Plaid  Provider must be “Plaid”

      

    Aside from SVB related errors, in some cases errors may be Plaid-related. For such errors SVB responds to clients with the error received from Plaid. SVB does not alter the formatting of pass-through Plaid errors.

     

    HTTP ERROR CODE PLAID ERRORS
    500 Plaid Internal Server Error
    503 Planned Maintenance
    400 Invalid Request
    400 Invalid Input

     

    Sample Plaid Error

     

    final plaid error

     

    When a Plaid error is encountered, SVB responds back to the client with Plaid’s error format including below fields:

    • Error Code
    • Error Message
    • Error Type
    • Request ID

    More information on Plaid-related errors can be found on: Plaid API Errors

     

    Support

     

    If you need to reach out to SVB to request support on a failed transaction, correlation ID from the SVB response header needs to be provided to identify the transaction. Clients can contact API support teamwith the correlation ID to request transaction details and support.

     

    Sample Correlation ID
     

    RESPONSE HEADER FIELD SAMPLE VALUE
    X-Svb-Correlation-Id

    ea6ca3f0-6738-11eb-9b6a-005056a4d951

     

    Clients can also reach out to Plaid for support on failed transactions, in such cases “request_id” in the response parameters will be used to request support. In addition to customer support, Plaid also hosts a status page to inform clients of their API status.