This guide details the various methods for creating and adding a bank account to a Counterparty. Counterparty bank accounts are called "External Accounts."

TAB-Pre-Built UI

This guide describes how to embed this pre-built Account Collection UI in your application. The Account Collection flow is currently tailored to collect domestic US account details, but in the future global account types and payment types will be supported.

Pre-Requisites

Organization ID: Found in your developer settings
API Key: Found in API Keys in your developer settings
Counterparty ID: The ID of the counterparty to which to add an account

🚧
Only use API keys server-side.
API keys are secret and should not be used directly in client-side applications. If you use an API key client-side or your key is exposed, you can delete the old key and generate a new one in your developer settings.

1. Create an Account Collection Flow

Create an account collection flow using the Create an Account Collection Flow API route. In addition to the counterparty_id, specify which payment_types you want the account to support. Modern Treasury will customize the embedded form to collect fields commonly required for the payment types.

curl --request POST \
	-u ORGANIZATION_ID:API_KEY \
	--url https://app.moderntreasury.com/api/account_collection_flows \
	-H 'Content-Type: application/json' \
	-d '{
		"counterparty_id": "37ba4454-dd33-4aa0-8906-0e2e4103e45c",
		"payment_types": ["ach"]
	}'

This API request will return an Account Collection Flow object. Save the client_token as it will be used in future steps.

{
  "id": "454e874b-ff1d-46e8-9d22-0464615cf1e0",
  "object": "account_collection_flow",
  "live_mode": true,
  "client_token": "ac-QVj2yTSt6qRNAzXQGKLHS9qfLF7Gs5JcCYHT5xztgjucGRbS6VfrJBpaNo5SrmfZ",
  "status": "pending",
  "payment_types": ["ach"],
  "counterparty_id": "c03581a8-c948-41a9-889a-e5228390fd80",
  "external_account_id": null,
  "created_at": "2023-02-18T03:23:48Z",
  "updated_at": "2023-02-18T03:23:48Z"
}

2. Retrieve Publishable API Key

Dashboard: Go to your Publishable API Keys page. There, you will find your Publishable API Keys. If you do not have one, create one.

3. Mount the Embeddable Flow

Add `modern-treasury-js`

Client-side: You first need to add modern-treasury-js to your application. We recommend installing the library from NPM, but you can also directly install the script from our CDN.

npm install --save @modern-treasury/modern-treasury-js

yarn add @modern-treasury/modern-treasury-js

<script src="https://cdn.moderntreasury.com/js/v1/modern-treasury.js"></script>

Initialize `ModernTreasury`

Client-side: Initialize ModernTreasury with your Publishable API Key from the previous step.

import { loadModernTreasury } from "@modern-treasury/modern-treasury-js";
 
const modernTreasury = await loadModernTreasury("publishable-test-MDAiy2...");

const modernTreasury = ModernTreasury("publishable-test-MDAiy2...");

Create an Embeddable Flow

Client-side: The next step is to create the EmbeddableFlow. You must pass the client_token from the previous step. While not required, we recommend defining an onSuccess callback to handle what happens after an end-user successfully completes the flow. Similarly, we recommend defining an onError callback to handle any unexpected errors. Visit createEmbeddableFlow documentation for full details.

import { EmbeddableFlow } from "@modern-treasury/modern-treasury-js";    

const embeddableFlow: EmbeddableFlow = modernTreasury.createEmbeddableFlow({
  clientToken: "ac-test-rWbNg...",
  onSuccess: (result) => { /* Navigate to your next page */ },
  onError: (error) => { /* Handle errors */ }
});

const embeddableFlow = modernTreasury.createEmbeddableFlow({
  clientToken: "ac-test-rWbNg...",
  onSuccess: (result) { /* Navigate to your next page*/ },
  onError: (error) => { /* Handle errors*/ }
});

(Optional) Customize Appearance

Client-side: You can customize the appearance of embeddable flows to match the look and feel of your application. Check out our createEmbeddableFlow documentation to see how to customize properties like colors and font.

Mount the Embeddable Flow

Client-side: Now that you have an EmbeddableFlow, you need to add it to the DOM. You can mount the flow to a valid CSS selector or a DOM element. After successfully mounting, the end-user will be able to start progressing through the flow.

embeddableFlow.mount("#put-iframe-here")

embeddableFlow.mount("#put-iframe-here")

Summary

After following all of these steps, you may have something that looks like this:

import React, { useEffect } from "react";
import { loadModernTreasury } from "@modern-treasury/modern-treasury-js";

function App() {
  useEffect(() => {
    const initModernTreasury = async () => {
      const modernTreasury = await loadModernTreasury("publishable-test-MDAiy2...");

      if (modernTreasury) {
        const embeddableFlow = modernTreasury.createEmbeddableFlow({
          clientToken: "ac-test-rWbNg...",
          onSuccess: (result) => { /* Handle Success */ },
          onError: (error) => { /* Handle Error */ }
        });

        embeddableFlow.mount("#put-iframe-here");
      }
    };

    void initModernTreasury();
  }, []);
  
  return (
    <div className="App">
      <div id="put-iframe-here" />
    </div>
  );
}

<!-- To run this example locally you'll need to serve the page, this can be done by -->
<!-- running `python3 -m http.server 8081` in the same directory as the html file. -->

<!DOCTYPE html>
<html>
  <script src="https://cdn.moderntreasury.com/js/v1/modern-treasury.js"></script>
  <body>
    <h1>My Heading</h1>
    <div id="put-iframe-here"></div>
  </body>
  <script>
    // Initialize Modern Treasury library
    const mt = ModernTreasury("publishable-test-MDAiy2...");

    // Create the Embeddable Flow
    const embeddableFlow = mt.createEmbeddableFlow({
      clientToken: "ac-test-rWbNg...",
      onSuccess: (result) => { /* Handle Success */ },
      onError: (error) => { /* Handle Error */  },
    });
    
    // Mount the Embeddable Flow
    embeddableFlow.mount("#put-iframe-here")
  </script>
</html>

4. End-User Submits Account Details

Client-side: Once the flow is mounted, the end-user will follow the embedded Account Collection flow and submit their account details. Once complete, we will create an ExternalAccount associated with the given Counterparty, save it to the AccountCollectionFlow, and move the AccountCollectionFlow#status to completed. We will also call the onSuccess callback so that you can customize your success behavior and navigate to the next page.

TAB-API

Pre-Requisites

Organization ID: Found in your developer settings
API Key: Found in API Keys in your developer settings
Counterparty ID: The ID of the counterparty to which to add an account

1. Collect account details

You may already have the external account details, having collected them perhaps in your own UI or other means. Once these details are collected, you will create an External Account using the API.

2. Create external account

Using the POST /external_accounts, create an external account using the previously collected information. When creating an external account, you can associate it to an existing counterparty. Let's assume that counterparty is Modern Baglery with an ID of 76ed8d23-564c-4895-b284-314327d9e574.

Sample Request

curl --request POST \
     --url https://app.moderntreasury.com/api/external_accounts \
     --header 'authorization: Basic ZjU5YTlhNGMtYjdjZS00MGE0LTkzZTgtN2RmODMyOTAxMzYwOnRlc3QtTXV3OG9IRjlHZUFhcWpFYTl3YW9HM1ZrQlNlclFhUVhTOGJLWlJHMUpjV3l1NVc0NHFiTmR0ZGZ3TnJQZzRDcw==' \
     --header 'content-type: application/json' \
     --data '
{
  "account_type": "other",
  "party_name": "Modern Baglery",
  "counterparty_id": "76ed8d23-564c-4895-b284-314327d9e574",
  "account_details": [
    {
      "account_number": "1234567890"
    }
  ],
  "routing_details": [
    {
      "routing_number_type": "aba",
      "routing_number": "121141822"
    }
  ]
}
'

{
  "id": "bca4a47f-e975-4940-85a6-d4e9621d7f81",
  "object": "external_account",
  "live_mode": false,
  "account_type": "other",
  "party_name": "Modern Baglery",
  "party_type": null,
  "party_address": null,
  "account_details": [
    {
      "id": "b40e53f2-f026-4309-89a0-da0e25430306",
      "object": "account_detail",
      "live_mode": false,
      "account_number_safe": "7890",
      "account_number_type": "other",
      "discarded_at": null,
      "created_at": "2024-02-17T00:59:20Z",
      "updated_at": "2024-02-17T00:59:20Z"
    }
  ],
  "routing_details": [
    {
      "id": "8e0bd4b5-a742-4e77-9243-6dc9e709ed46",
      "object": "routing_detail",
      "live_mode": false,
      "payment_type": null,
      "routing_number": "121141822",
      "routing_number_type": "aba",
      "bank_name": "Bank of America California National Association",
      "bank_address": {
        "id": "81d11b6a-e8a0-436a-b0ec-d550ddbe4f77",
        "object": "address",
        "live_mode": false,
        "line1": "345 Montgomery St",
        "line2": null,
        "locality": "San Francisco",
        "region": "CA",
        "postal_code": "94104-1802",
        "country": "US",
        "created_at": "2024-01-04T19:12:32Z",
        "updated_at": "2024-01-04T19:12:32Z"
      },
      "discarded_at": null,
      "created_at": "2024-02-17T00:59:20Z",
      "updated_at": "2024-02-17T00:59:20Z"
    }
  ],
  "name": null,
  "metadata": {},
  "verification_status": "unverified",
  "contact_details": [],
  "ledger_account_id": null,
  "counterparty_id": "76ed8d23-564c-4895-b284-314327d9e574",
  "discarded_at": null,
  "created_at": "2024-02-17T00:59:20Z",
  "updated_at": "2024-02-17T00:59:20Z"
}

TAB-Dashboard

Pre-Requisites

Counterparty: An existing Counterparty to which to add an account

Add an External Account

In the Modern Treasury dashboard, navigate to Counterparties. Filter or paginate to find the desired Counterparty and click to view the details.
From the “Actions” dropdown menu, click "Add or Edit Bank Accounts" From here, you will see all of the existing External Accounts for that Counterparty which you can edit or delete.

Click "Add Bank Account" and select the type of account you wish to create from the dropdown menu. Begin filling out the form for the new External Account.

Field	Details
Name on Account	This is required; you will need to enter the legal name that is attached to the bank account.
Account Nickname	This is not required; you can use this to easily identify the Counterparty's External Account as needed. This is for internal use only.
Counterparty Type	This is not required, but is useful; this helps distinguish between a PPD and a CCD payment (these are Standard Entry Class codes for ACH).
Account Type	Not required; this is to identify whether the account is a checking or savings account.
Address on Account	This is required for wires.
International Details (IBAN, Sort Code, SWIFT, etc.)	This is required for international wire payments.

Click "Save" to finish creating the External Account.

Pre-Requisites

🚧Only use API keys server-side.

1. Create an Account Collection Flow

2. Retrieve Publishable API Key

3. Mount the Embeddable Flow

Add modern-treasury-js

Initialize ModernTreasury

Create an Embeddable Flow

(Optional) Customize Appearance

Mount the Embeddable Flow

Summary

4. End-User Submits Account Details

Pre-Requisites

1. Collect account details

2. Create external account

Sample Request

Pre-Requisites

Add an External Account

🚧
Only use API keys server-side.

Add `modern-treasury-js`

Initialize `ModernTreasury`