Hey! These docs are for version 1.0, which is no longer officially supported. Click here for the latest version, 1.1!

Verifying with Plaid

Modern Treasury and Plaid have partnered to enable our mutual customers to use Plaid to authenticate and collect bank account details without ever touching sensitive data like bank account numbers.

To use Plaid with Modern Treasury, first follow the instructions on Plaid's docs. These will walk you through how to use Plaid to get a processor_token for your counterparty. Ultimately, you will get a response from Plaid that looks like what is below.

{
  "processor_token": "processor-sandbox-0asd1-a92nc",
  "request_id": "[Unique request ID]"
}

The processor_token corresponds to the user's bank account that was just connected with Plaid. The token can be passed to Modern Treasury when creating the external account on a counterparty. Modern Treasury will then pull the bank details from Plaid directly. If there is an error, the request will fail.

curl --request POST \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/counterparties \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe",
    "accounts": [
      {
        "plaid_processor_token": "processor-sandbox-0asd1-a92nc"
      }
    ]
  }'

This request will create a counterparty with an external account. The external account's banking information will have been automatically pulled from Plaid. The external account's verification status will be verified.

Once the counterparty has been created, payment orders can be created that use the counterparty's external account ID. To see how to do this, follow the instructions in our Quickstart Guide under Create a Counterparty.

How to handle a Plaid item that needs to be refreshed

When you use Plaid to connect to your counterparty's bank accounts (which Plaid calls "items"), the connections may get into an invalid state. This could happen if a user changed their password or 2FA code, for example.

If you are only using Modern Treasury's Plaid integration to pull banking details from Plaid, there is nothing you have to do. Modern Treasury has already recorded the user's banking information as an external_account.

However, if you are using the NSF protection feature, you must refresh the connection to the item through Plaid. While the Plaid item connection is invalid, Modern Treasury will be unable to pull balances via Plaid and you may see the nsf_deferment or nsf_plaid_error_but_processing webhooks on your payment order.

When Plaid's connection to an item gets into an invalid state, Plaid will prompt you to refresh the link. The item will have entered the state ITEM_LOGIN_REQUIRED , and Plaid will notify you via a webhook. To refresh the connection, you can use Plaid Link in update mode to prompt the user to update authentication information, per the instructions here.

Once the user has reauthenticated their account, you will be able to use the original access and processor tokens again. Plaid does not require you to rotate these tokens when an item is reconnected as it is the same underlying item.