Modern Treasury API Documentation

Welcome to Modern Treasury. You'll find comprehensive guides and documentation to help you start working with Modern Treasury APIs as quickly as possible, as well as support if you get stuck.

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 via their Plaid Auth product. 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.

Using Plaid Identity

Plaid offers a product called Identity that provides additional information about your user's connected bank accounts. Plaid Auth will only provide the minimum set of information required to pay a counterparty, which is their account number, routing number, and account type. Although this is generally all that is needed to initiate payments, it can be helpful to also have the identity information on a bank account. For example, address information are required for checks and wires. Through our integration with Plaid Identity, Modern Treasury can pull your counterparty's name and address associated with the bank account.

We do not enable Plaid Identity by default because this is an additional charge from Plaid. If you would like to leverage Plaid Identity, visit your Organization Settings page and enable the integration in your Plaid Settings section. Once it is turned on, Plaid Identity will automatically be used for all counterparties created with processor tokens.

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.

Updated about a month ago


Verifying with Plaid


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.