Instant Account Verification v2 - Plaid Integration
Countries:
US

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.

In addition to account verification, clients can also verify the balance on the account against the ACH transfer amount (this functionality is not available for recurring payments using the same processor token)

Plaid integration diagram

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

Step Actors Description
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.

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:

Plaid institution selection

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

There are two differences when submitting an ACH transfer with a Plaid processor token:

  1. Client will need to call the /v2/transfer/domestic-verified-achs endpoint (instead of v2/transfer/domestic-achs)
  2. Client will need to pass in the processor token from Plaid instead of receiver account information.

 

Parameters:

There are two data sets included in an ACH API request in v2, batch details and transfers. Batch details include the information regarding the batch of transfers and transfers include specific payment information (there can be one or multiple transfers).

 

Batch Details

Name Type Description
svb_account_number string

 SVB bank account number originating the ACH transfer.

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

direction

required

enum(“credit”, “debit”)  Direction of the transfer.
effective_entry_date date  Date when the transfer should take place. Defaults to tomorrow’s date.

sec_code

required

enum(“ccd”, “ppd”, “web”)  SEC code to be used for the ACH transfer.
settlement_priority enum(“standard”, “same-day”)  Determines priority/urgency of the settlement. Defaults to standard service.

 

Transfers

Name Type Description

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".
identification_number 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.

counterparty_name

required

string  Name of the receiver account holder.
provider_service

 

 

required

string

 "PLAID" -  if the client only wants to perform IAV on the account.

 "PLAID_BALANCE_CHECK" - if the client wants to perform IAV + balance check on the account.

provider_id

required

string  Processor token received from Plaid.

 

 

Sample Postman Request and Response

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

Plaid Postman request

Sample Postman response:

Plaid Postman response

 

Troubleshooting and Support

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

Source Error Description
       SVB  Parameter svb_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

  

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

Plaid sample 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 team with 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.