Link External Accounts with Plaid

Overview

Account holders can connect external bank accounts to a Highnote financial account to move funds in and out via different payment rails. Highnote supports two connection types: verified and non-verified.

Highnote has partnered with Plaid to verify and connect external bank accounts securely and with NACHA compliance.

Integration paths

The Highnote platform offers three integration paths for Plaid:

Hosted URL Integration: No-code solution where Highnote manages the Plaid relationship on your behalf. Best for reducing compliance burden and frontend development.
Plaid SDK Integration: Highnote manages the Plaid relationship, but you integrate the Plaid Link SDK into your application for a native experience.
Connect verified account with Plaid: You maintain a direct relationship with Plaid, authenticate users in your application, and pass verification details to Highnote via processor_token.

Contact Highnote

Contact your Highnote representative about Plaid products and pricing available for your program.

External bank account types

You can transfer funds into or out of Highnote from an external bank account.

Fund-in transfers: A funds transfer from an external account to a Highnote financial account. Fund-in transfers require external account verification.
Fund-out transfers: A funds transfer from a Highnote financial account to an external account. Fund-out transfers do not require verification of the external account and can only be initiated on card products with a cash deposit (ex: debit and secured debit cards).

There are two types of Highnote external financial accounts:

Account Type	Verified	Transfer Method
`ExternalFinancialBankAccount`	Yes	Fund-in or Fund-out
`NonVerifiedExternalUSFinancialBankAccount`	No	Fund-out on debit cards

Prerequisite: Complete Plaid onboarding form

reduce compliance burden

Delegating your Plaid relationship to Highnote reduces your compliance requirements as Highnote provides and manages a secure vault. Using the no-code hosted URL solution also removes your need for frontend SDK development.

All users should complete Highnote's Plaid Onboarding form. The Hosted URL and Plaid SDK integrations both require completing the onboarding form.

The form requests the information outlined below.

Company / Application Details

Company email, name, URL
Legal name and address
Assets Under Management (amount and currency)
Application (or company) name and icon

Integration Details

Highnote supports Plaid's Auth, Balance, and Identity payment products by default.

Plaid Link configuration: Customizable or Plaid default
Integration flow: Hosted URL (no-code) or SDK
SDKs to integrate: Web, iOS, Android, React Native, Mobile webview.
Redirect URI. When integrating via SDK, this is redirect_uri or package_name (which is the redirectUri used in Step 2):
- Web SDK: Web SDK redirect URI
- Apple iOS: Universal Link redirect URI
- Android, React Native: Android package name

redirect URI per SDK integration

Highnote requires a redirect URI per SDK integration even if the mutation input variable redirectUri is optional.

Contacts

Technical Contact name and email
Billing Contact name and email
Customer Support email, and optionally phone, URL, link update URL

What's Possible

Feature	Supported	Description
Link customization	Yes	Subscribers can customize their integrations after completing the Highnote Onboarding form.
US OAuth institutions	Yes	Highnote handles registration with all Plaid-supported financial institutions.
Developer log access	Passed-through	Highnote surfaces Plaid integration-related errors under `userError` in the API mutation response.

Testing your Plaid workflows

info

Highnote only supports SAVINGS and CHECKING account types at this time.

You can test your Plaid workflows with dummy data from Plaid. Some banks, such as Chase, are supported with restrictions. Refer to the Plaid documentation for support:

Chase restrictions are:

Must have full Production access for at least one product and have also completed the OAuth registration process
Chase has an additional waiting period; it may take up to two weeks after Production approval for Chase Production access to be granted. You must also complete the Security Questionnaire.

Authentication methods

Both the Hosted URL and Plaid SDK integrations use Plaid Link, which supports the following authentication methods. When an end user connects their bank account, Plaid automatically selects the best method based on the capabilities of the user's financial institution. No integration changes are required.

Method	Verification time	How it works
Instant Auth	Instant	User logs in with their bank credentials.
Instant Micro-deposits	~5 seconds	Plaid sends a $0.01 deposit via RTP or FedNow. User enters the code from the deposit description.
Automated Micro-deposits	1–2 business days	Plaid initiates a micro-deposit that verifies automatically without user action.
Same-day Micro-deposits	Up to 1 business day	Plaid sends a Same Day ACH deposit. User enters the code from the deposit description.

Hosted URL Integration

To connect a verified Plaid account with Highnote via the no-code hosted solution:

Step 0: Complete Highnote's Plaid Onboarding form.
Step 1: Integrate Plaid Hosted URL with your application.
Step 2: Create a hosted_link_url with the Highnote API (and flow: WEB_HOSTED).
Step 3: Query the status of your external account link.

Refer to the Plaid Hosted Link documentation for more guidance.

Step 1. Integrate Plaid Hosted Link

Refer to the Plaid Hosted Link documentation to integrate Plaid Link into your application.

Step 2. Create hosted URL

Create a Highnote hosted_link_url with flow set to WEB_HOSTED. You can send the generated URL to an end user to start the Hosted Link session.

Use the following mutation to generate a hosted_link_url for an account holder (or end user):

GenerateVerifiedExternalBankAccountLinkToken

Query

mutation GenerateVerifiedExternalBankAccountLinkToken(
  $input: GenerateVerifiedExternalBankAccountLinkTokenInput!
) {
  generateVerifiedExternalBankAccountLinkToken(input: $input) {
    __typename
    ... on GenerateVerifiedExternalBankAccountExternalLinkToken {
      externalLinkToken
      expirationDate
      accountHolder {
        __typename
        ... on USPersonAccountHolder {
          id
          email
          dateOfBirth
          externalId
          updatedAt
          createdAt
        }
        ... on USBusinessAccountHolder {
          id
        }
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
  }
}

Variables

{
  "input": {
    "accountHolderId": "og_ah02fea2050cf49b4be8b96be4437892dbba",
    "linkExperience": {
      "flow": "ANDROID_SDK",
      "redirectUri": "com.example"
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "generateVerifiedExternalBankAccountLinkToken": {
      "__typename": "GenerateVerifiedExternalBankAccountExternalLinkToken",
      "externalLinkToken": "link-sandbox-b1b8b1ef-065b-18e9-aab3-ee396895efda",
      "expirationDate": "2024-12-03T21:19:01.056Z",
      "accountHolder": {
        "__typename": "USBusinessAccountHolder",
        "id": "og_ah02fea2050cf49b4be8b96be4437892dbba"
      }
    }
  },
  "extensions": {
    "requestId": "b3ef5ec2-92c5-9644-8108-3650398d8f9d",
    "rateLimit": {
      "cost": 11,
      "limit": 60060,
      "remaining": 60049
    }
  }
}

Step 3. Get link status

Monitor the status of the external bank account to check whether the account holder successfully linked their account.

You can either subscribe to external bank account events with a webhook, or poll with the following query.

AccountHolderProvisioning

Query

query AccountHolderProvisioning($id: ID!) {
  node(id: $id) {
    ... on AccountHolderProvisioning {
      __typename
      id
      idempotencyKey
      createdAt
      updatedAt
      outcome {
        status
      }
      workflowActions {
        __typename
        id
        action
        actionInput {
          linkVerifiedExternalBankAccountInput {
            publicToken
          }
        }
        outcome {
          status
        }
        executionOrder
        node {
          __typename
          ... on UserError {
            errors {
              errorPath
              code
              description
            }
          }
          ... on WorkflowActionResultOutcome {
            createdAt
            updatedAt
            result {
              __typename
              ... on WorkflowActionLinkVerifiedExternalBankAccountResult {
                externalFinancialBankAccounts {
                  __typename
                  id
                  name
                  accountStatus
                  createdAt
                  updatedAt
                  provider
                  externalBankAccountDetails {
                    last4
                    id
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Variables

{
  "id": "prvwo_6b71451ab658486a8f748db580edc081"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "__typename": "AccountHolderProvisioning",
      "id": "prvwo_54aba9ffaf2c4ad986c75a6ea3124d91",
      "idempotencyKey": "IDEMPOTENCY-KEY",
      "createdAt": "2024-12-03T20:58:11.449Z",
      "updatedAt": "2024-12-03T20:58:14.747Z",
      "outcome": {
        "status": "COMPLETED"
      },
      "workflowActions": [
        {
          "__typename": "AccountHolderProvisioningWorkflowAction",
          "id": "prvwa_8963b95a713b4847853888ee255f9c56",
          "action": "LINK_VERIFIED_EXTERNAL_BANK_ACCOUNT",
          "actionInput": {
            "linkVerifiedExternalBankAccountInput": {
              "publicToken": "public-sandbox-97435641-d2cf-421f-8d60-c0fe568b4ae2"
            }
          },
          "outcome": {
            "status": "COMPLETED"
          },
          "executionOrder": 1,
          "node": {
            "__typename": "WorkflowActionResultOutcome",
            "createdAt": "2024-12-03T20:58:11.449Z",
            "updatedAt": "2024-12-03T20:58:11.449Z",
            "result": {
              "__typename": "WorkflowActionLinkVerifiedExternalBankAccountResult",
              "externalFinancialBankAccounts": [
                {
                  "__typename": "ExternalFinancialBankAccount",
                  "id": "ac_ba22446a041287274d81af25bb83eeba46b1",
                  "name": "Plaid Checking",
                  "accountStatus": "ACTIVE",
                  "createdAt": "2024-12-03T20:58:14.222Z",
                  "updatedAt": "2024-12-03T20:58:14.222Z",
                  "provider": "PLAID_RESELLER",
                  "externalBankAccountDetails": {
                    "last4": "0052",
                    "id": "xa_2614de7b7dc441c497c7b98e7324a136"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  },
  "extensions": {
    "requestId": "e9c64e5d-3df7-9464-9ebc-19c39cb08168",
    "rateLimit": {
      "cost": 10,
      "limit": 60060,
      "remaining": 60050
    }
  }
}

Plaid SDK Integration

note

Refer to the Plaid Link documentation on SDK integration for more guidance.

To connect a verified account with Highnote via SDK:

Step 0: Complete Highnote's Plaid Onboarding form.
Step 1: Integrate Plaid Link with your application.
Step 2: Create a link_token with the Highnote API (e.g., flow: IOS_SDK).
Step 3: Initiate Plaid Link by using the link_token to retrieve a public_token.
Step 4: Link an external bank account by sending the public_token to Highnote.
Step 5: Query the status of your external account link.

Step 1. Integrate Plaid Link

Refer to the Plaid Link documentation to integrate the Plaid Link SDK into your application.

Step 2. Create link token

Create a Highnote link_token with flow set to your chosen SDK. Use this token to initiate Plaid Link (in the next step) and generate a public_token in Plaid.

In the Test environment, Highnote gives you a link_token to generate a public_token in Plaid's Sandbox environment. Your card product must be configured by Highnote for the Plaid integration.

Step 3. Initialize Plaid Link

Generate a public_token in Plaid with the link_token from Step 2 to initialize Plaid Link. Plaid Link provides a temporary public_token in the onSuccess callback.

The details for passing the link_token vary by platform. See the page for your specific platform integration: web, iOS, Android, React Native, or mobile webview.

In Highnote's Test environment, you can create a public_token in all three of Plaid's API environments:

Plaid Sandbox: Test simulated users
Plaid Limited Production: Test live users
Plaid Production: Production environment for when you're ready to go live and have valid Highnote Live environment API keys.

Step 4. Link external account with public token

Call the ProvisionAccountHolder mutation to link an external bank account with Plaid's ephemeral public_token. Highnote will create a persistent access_token and use it to call various Plaid products for the account holder.

In the Test environment, provide the public_token you received from Plaid's Sandbox environment or one of the simulated values below.

Simulated Public Token Value	Result
public-token-success	Success
public-token-no-ach-account-number	Failure
public-token-no-routing-account-number	Failure
public-token-wrong-sub-type	Failure
public-token-wrong-currency-code	Failure
public-token-wrong-length-account-number	Failure
public-token-wrong-length-routing-number	Failure
public-token-non-digit-routing-number	Failure
public-token-not-found	Failure
public-token-institution-down	Failure
public-token-item-login-required	Failure

ProvisionAccountHolder

Query

mutation ProvisionAccountHolder($input: ProvisionAccountHolderInput!) {
  provisionAccountHolder(input: $input) {
    __typename
    ... on AccountHolderProvisioning {
      id
      accountHolder {
        __typename
        ... on USPersonAccountHolder {
          id
          name {
            givenName
          }
        }
        ... on USBusinessAccountHolder {
          id
        }
      }
      workflowActions {
        id
        action
        outcome {
          status
        }
      }
    }
  }
}

Variables

{
  "input": {
    "idempotencyKey": "IDEMPOTENCY-KEY",
    "accountHolderId": "og_ah02fea2050cf49b4be8b96be4437892dbba",
    "actions": [
      "LINK_VERIFIED_EXTERNAL_BANK_ACCOUNT"
    ],
    "actionInput": {
      "linkVerifiedExternalBankAccountInput": {
        "publicToken": "public-sandbox-97435641-d2cf-421f-8d60-c0fe568b4ae2"
      }
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "provisionAccountHolder": {
      "__typename": "AccountHolderProvisioning",
      "id": "prvwo_6b71451ab658486a8f748db580edc081",
      "accountHolder": {
        "__typename": "USBusinessAccountHolder",
        "id": "og_ah02fea2050cf49b4be8b96be4437892dbba"
      },
      "workflowActions": [
        {
          "id": "prvwa_340aee832b6148c08ae59fe2067db1d2",
          "action": "LINK_VERIFIED_EXTERNAL_BANK_ACCOUNT",
          "outcome": {
            "status": "INITIATED"
          }
        }
      ]
    }
  },
  "extensions": {
    "requestId": "fa750ebf-a141-9849-adc0-74817358b23b",
    "rateLimit": {
      "cost": 14,
      "limit": 60060,
      "remaining": 60046
    }
  }
}

Step 5. Get link status

Monitor the status of the external bank account to check whether the account holder successfully linked their account.

You can either subscribe to external bank account events with a webhook, or poll with the following query.

AccountHolderProvisioning

Query

query AccountHolderProvisioning($id: ID!) {
  node(id: $id) {
    ... on AccountHolderProvisioning {
      __typename
      id
      idempotencyKey
      createdAt
      updatedAt
      outcome {
        status
      }
      workflowActions {
        __typename
        id
        action
        actionInput {
          linkVerifiedExternalBankAccountInput {
            publicToken
          }
        }
        outcome {
          status
        }
        executionOrder
        node {
          __typename
          ... on UserError {
            errors {
              errorPath
              code
              description
            }
          }
          ... on WorkflowActionResultOutcome {
            createdAt
            updatedAt
            result {
              __typename
              ... on WorkflowActionLinkVerifiedExternalBankAccountResult {
                externalFinancialBankAccounts {
                  __typename
                  id
                  name
                  accountStatus
                  createdAt
                  updatedAt
                  provider
                  externalBankAccountDetails {
                    last4
                    id
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Variables

{
  "id": "prvwo_6b71451ab658486a8f748db580edc081"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "__typename": "AccountHolderProvisioning",
      "id": "prvwo_54aba9ffaf2c4ad986c75a6ea3124d91",
      "idempotencyKey": "IDEMPOTENCY-KEY",
      "createdAt": "2024-12-03T20:58:11.449Z",
      "updatedAt": "2024-12-03T20:58:14.747Z",
      "outcome": {
        "status": "COMPLETED"
      },
      "workflowActions": [
        {
          "__typename": "AccountHolderProvisioningWorkflowAction",
          "id": "prvwa_8963b95a713b4847853888ee255f9c56",
          "action": "LINK_VERIFIED_EXTERNAL_BANK_ACCOUNT",
          "actionInput": {
            "linkVerifiedExternalBankAccountInput": {
              "publicToken": "public-sandbox-97435641-d2cf-421f-8d60-c0fe568b4ae2"
            }
          },
          "outcome": {
            "status": "COMPLETED"
          },
          "executionOrder": 1,
          "node": {
            "__typename": "WorkflowActionResultOutcome",
            "createdAt": "2024-12-03T20:58:11.449Z",
            "updatedAt": "2024-12-03T20:58:11.449Z",
            "result": {
              "__typename": "WorkflowActionLinkVerifiedExternalBankAccountResult",
              "externalFinancialBankAccounts": [
                {
                  "__typename": "ExternalFinancialBankAccount",
                  "id": "ac_ba22446a041287274d81af25bb83eeba46b1",
                  "name": "Plaid Checking",
                  "accountStatus": "ACTIVE",
                  "createdAt": "2024-12-03T20:58:14.222Z",
                  "updatedAt": "2024-12-03T20:58:14.222Z",
                  "provider": "PLAID_RESELLER",
                  "externalBankAccountDetails": {
                    "last4": "0052",
                    "id": "xa_2614de7b7dc441c497c7b98e7324a136"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  },
  "extensions": {
    "requestId": "e9c64e5d-3df7-9464-9ebc-19c39cb08168",
    "rateLimit": {
      "cost": 10,
      "limit": 60060,
      "remaining": 60050
    }
  }
}

Connect verified account with Plaid

As a subscriber, you can integrate with Highnote while maintaining your direct relationship with Plaid. You authenticate end-user bank accounts in your applications with Plaid, and then securely pass verification details to Highnote with processor_token.

Refer to the Plaid documentation, Add Highnote to your app.

To connect a verified account with Plaid:

Step 0: Set up your Plaid account and sign up for Plaid API keys.
Step 1: Enable your Plaid account for Highnote integration on the Plaid dashboard.
Step 2: Create a link_token in Plaid.
Step 3: Get Plaid's Highnote processor_token by exchanging it with the link_token.
Step 4: Link an external bank account by sending the processor_token to Highnote.
Step 5: Test your Plaid connections.

Prerequisite: Set up your Plaid account

note

This step is a prerequisite to connecting a verified account with Plaid.

Create a business or developer Plaid account. On the Plaid dashboard, go to the Keys tab and create Plaid API keys.

Step 1. Enable Plaid account for Highnote

important

Highnote requires only one bank account. If a user has multiple bank accounts, the accounts array from Plaid may contain information from all of them. To ensure the accounts array contains only one, go to the Plaid dashboard and set Account Select to "enabled for one account".

Follow the Plaid docs to enable your Plaid account for Highnote integration. On the Plaid dashboard:

Go to the Integrations tab, click enable Highnote.
Go to the Application tab, complete your application profile.
Go to the Link customization tab, select the use cases you want to use with Highnote.

Step 2. Create a Plaid link token

Follow the Plaid docs to create a one-time Plaid link_token. You will use this token to exchange it for a "Highnote" processor_token to send to Highnote.

Step 3. Get Plaid's Highnote processor token

Follow the Plaid docs to exchange your link_token for a Plaid "Highnote" processor_token.

Step 4. Link external account with processor token

Plaid errors

Processor token errors must be resolved with Plaid. Refer to Plaid Errors.

Use the AddExternalBankAccountVerifiedThroughPlaid mutation to link an external bank account with Plaid's processor_token. Highnote retrieves the account number, routing number, and account type from Plaid, and links the information to the associated account holder for future payment usage.

If the response includes a processor token error, get a new processor_token from Plaid and reattempt adding the external bank account. All processor token errors must be resolved with Plaid. In some cases, your customer may need to resubmit their bank account credentials for you to retrieve a new processor_token. See the Plaid docs for a list of possible Plaid-related errors.

Use the following mutation to add an external bank account using Plaid:

AddExternalBankAccountVerifiedThroughPlaid

Query

mutation AddExternalBankAccountVerifiedThroughPlaid(
  $input: AddExternalBankAccountVerifiedThroughPlaidInput!
) {
  addExternalBankAccountVerifiedThroughPlaid(input: $input) {
    __typename
    ... on ExternalFinancialBankAccount {
      id
      name
      provider
      createdAt
      updatedAt
      owner {
        __typename
      }
      ledgers {
        id
        name
      }
      externalBankAccountDetails {
        id
        createdAt
        updatedAt
        last4
        type
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "accountHolderId": "ACCOUNT_HOLDER_ID",
    "externalToken": {
      "value": "processor-token-success"
    }
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "addExternalBankAccountVerifiedThroughPlaid": {
      "__typename": "ExternalFinancialBankAccount",
      "id": "ACCOUNT_HOLDER_ID",
      "name": "Plaid Checking",
      "provider": "SIMULATED",
      "createdAt": "2022-09-09T19:33:02.822Z",
      "updatedAt": "2022-09-09T19:33:02.881Z",
      "owner": {
        "__typename": "USPersonAccountHolder"
      },
      "ledgers": [
        {
          "id": "FINANCIAL_ACCOUNT_ID",
          "name": "AVAILABLE_CASH"
        },
        {
          "id": "FINANCIAL_ACCOUNT_ID",
          "name": "CASH"
        }
      ],
      "externalBankAccountDetails": {
        "id": "EXTERNAL_BANK_ACCOUNT_ID",
        "createdAt": "2022-09-09T19:33:02.822Z",
        "updatedAt": "2022-09-09T19:33:02.880Z",
        "last4": "9606",
        "type": "CHECKING"
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Step 5. Test Plaid connections

To test Plaid, you will need to use your processor_tokens. You can create Highnote processor_tokens in all three of Plaid's API environments:

Plaid Sandbox: Test simulated users
Plaid Development: Test live users
Plaid Production: Production environment for when you're ready to go live and have valid Highnote Live environment API keys

Connect a non-verified account

info

Non-verified external bank accounts can only be used to receive funds from a Highnote financial account. They can never be used to move funds into Highnote.

Non-verified accounts are those that have not been verified by a third party like Plaid. The most common use case for a non-verified external bank account is to return funds to an account holder in the event of account closure. You cannot move funds into Highnote with a non-verified account.

When connecting an external bank account, your account holder must provide the following external account information:

Routing number
Account number
Account type: Checking or savings

Use the following mutation to add a non-verified external bank account. Optionally, a nickname can be assigned to the non-verified account for reference.

AddNonVerifiedExternalUSFinancialBankAccount

Query

mutation addNonVerifiedExternalUSFinancialBankAccount(
  $input: AddNonVerifiedExternalUSFinancialBankAccountInput!
) {
  addNonVerifiedExternalUSFinancialBankAccount(input: $input) {
    __typename
    ... on NonVerifiedExternalUSFinancialBankAccount {
      id
      name
      createdAt
      updatedAt
      externalBankAccountDetails {
        id
        last4
        type
        routingNumber
        createdAt
        updatedAt
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "routingNumber": "111000025",
    "accountNumber": "12345678910",
    "name": "My Checking Account",
    "accountHolderId": "ACCOUNT_HOLDER_ID",
    "bankAccountType": "CHECKING"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "addNonVerifiedExternalUSFinancialBankAccount": {
      "__typename": "NonVerifiedExternalUSFinancialBankAccount",
      "id": "EXTERNAL_FINANCIAL_ACCOUNT_ID",
      "name": "My Checking Account",
      "createdAt": "2022-02-09T17:10:56.662Z",
      "updatedAt": "2022-02-09T17:10:56.662Z",
      "externalBankAccountDetails": {
        "id": "EXTERNAL_BANK_ACCOUNT_ID",
        "last4": "8910",
        "type": "CHECKING",
        "routingNumber": "111000025",
        "createdAt": "2022-02-09T17:10:56.662Z",
        "updatedAt": "2022-02-09T17:10:56.662Z"
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

List external accounts

You can view and present a list of an account holder's external bank accounts using the following query:

ListAccountHolders

Query

query ListAccountHolders($first: Int) {
  businessAccountHolders(first: $first) {
    pageInfo {
      startCursor
      endCursor
      hasNextPage
      hasPreviousPage
    }
    edges {
      cursor
      node {
        ...accountHolder
      }
    }
  }
}

fragment accountHolder on USBusinessAccountHolder {
  id
  externalFinancialAccounts {
    edges {
      node {
        ... on ExternalFinancialAccount {
          __typename
          ... on ExternalFinancialBankAccount {
            id
            name
            ledgers {
              name
            }
            externalBankAccountDetails {
              id
              last4
              type
              routingNumber
              createdAt
              updatedAt
            }
          }
        }
      }
    }
  }
}

Variables

{
  "first": 20
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "businessAccountHolders": {
      "pageInfo": {
        "startCursor": "start-cursor",
        "endCursor": "end-cursor",
        "hasNextPage": true,
        "hasPreviousPage": false
      },
      "edges": [
        {
          "cursor": "some-cursor",
          "node": {
            "id": "BUSINESS_ACCOUNT_HOLDER_ID",
            "externalFinancialAccounts": {
              "pageInfo": {
                "startCursor": "start-cursor",
                "endCursor": "end-cursor",
                "hasNextPage": true,
                "hasPreviousPage": false
              },
              "edges": [
                {
                  "cursor": "some-cursor",
                  "node": {
                    "__typename": "ExternalFinancialBankAccount",
                    "id": "EXTERNAL_ACCOUNT_ID",
                    "name": "Plaid Checking",
                    "last4": "2730",
                    "type": "CHECKING",
                    "routingNumber": "011401533",
                    "createdAt": "2022-02-25T17:01:12.322Z",
                    "updatedAt": "2022-02-25T17:01:12.523Z",
                    "ledgers": [
                      {
                        "name": "AVAILABLE_CASH"
                      }
                    ]
                  }
                }
              ]
            }
          }
        }
      ]
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Disconnect external account

The CloseExternalFinancialBankAccount mutation lets you support the following disconnect experiences:

Provide an interface for account holders to disconnect external accounts from your app or website.
Provide an interface for your organization's support team to disconnect external accounts.

Guidelines for disconnecting an external bank account:

When the external bank account is disconnected, all scheduled payments associated with it are canceled. If the Highnote financial account associated with the external bank account has a pending payment, the account cannot be disconnected until all pending payments are settled.
Customers must re-verify their identity to reconnect a verified external bank account to their Highnote financial account.
Customers do not need to re-verify their identity to reconnect a non-verified external bank account to their Highnote financial account.

Use the following mutation to disconnect a verified or non-verified external bank account:

CloseExternalFinancialBankAccount

Query

mutation CloseExternalFinancialBankAccount(
  $input: CloseExternalFinancialBankAccountInput!
) {
  closeExternalFinancialBankAccount(input: $input) {
    __typename
    ... on ExternalFinancialBankAccount {
      id
      name
      accountStatus
      createdAt
      updatedAt
      owner {
        __typename
        ... on USBusinessAccountHolder {
          primaryAuthorizedPerson {
            id
          }
          businessProfile {
            id
          }
        }
      }
      ledgers {
        id
        name
      }
      features {
        __typename
        enabled
      }
      externalBankAccountDetails {
        id
        createdAt
        updatedAt
        last4
        type
        routingNumber
      }
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "externalFinancialBankAccountId": "EXTERNAL_BANK_ACCOUNT_ID"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "closeExternalBankAccount": {
      "__typename": "ExternalFinancialBankAccount",
      "id": "EXTERNAL_BANK_ACCOUNT_ID",
      "name": "Plaid Checking",
      "accountStatus": "CLOSED",
      "createdAt": "2022-02-23T14:25:17.334Z",
      "updatedAt": "2022-02-23T14:25:18.006Z",
      "owner": {
        "__typename": "USBusinessAccountHolder",
        "primaryAuthorizedPerson": {
          "id": "PRIMARY_AUTHORIZED_PERSON_ID"
        },
        "businessProfile": {
          "id": "BUSINESS_PROFILE_ID"
        }
      },
      "ledgers": [
        {
          "id": "FINANCIAL_ACCOUNT_ID",
          "name": "AVAILABLE_CASH"
        },
        {
          "id": "FINANCIAL_ACCOUNT_ID",
          "name": "CASH"
        }
      ],
      "features": [
        {
          "__typename": "AchCapableFinancialAccountFeature",
          "enabled": true
        },
        {
          "__typename": "VendorProvidedBankFinancialAccountFeature",
          "enabled": true
        }
      ],
      "externalBankAccountDetails": {
        "id": "EXTERNAL_BANK_ACCOUNT_ID",
        "createdAt": "2022-02-23T14:25:17.336Z",
        "updatedAt": "2022-02-23T14:25:17.995Z",
        "last4": "8546",
        "type": "CHECKING",
        "routingNumber": "011401533"
      }
    }
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Overview​

Integration paths​

External bank account types​

Prerequisite: Complete Plaid onboarding form​

Company / Application Details​

Integration Details​

Contacts​

What's Possible​

Testing your Plaid workflows​

Authentication methods​

Hosted URL Integration​

Step 1. Integrate Plaid Hosted Link​

Step 2. Create hosted URL​

GenerateVerifiedExternalBankAccountLinkToken​

Step 3. Get link status​

AccountHolderProvisioning​

Plaid SDK Integration​

Step 1. Integrate Plaid Link​

Step 2. Create link token​

Step 3. Initialize Plaid Link​

Step 4. Link external account with public token​

ProvisionAccountHolder​

Step 5. Get link status​

AccountHolderProvisioning​

Connect verified account with Plaid​

Prerequisite: Set up your Plaid account​

Step 1. Enable Plaid account for Highnote​

Step 2. Create a Plaid link token​

Step 3. Get Plaid's Highnote processor token​

Step 4. Link external account with processor token​

AddExternalBankAccountVerifiedThroughPlaid​

Step 5. Test Plaid connections​

Connect a non-verified account​

AddNonVerifiedExternalUSFinancialBankAccount​

List external accounts​

ListAccountHolders​

Disconnect external account​

CloseExternalFinancialBankAccount​

Overview

Integration paths

External bank account types

Prerequisite: Complete Plaid onboarding form

Company / Application Details

Integration Details

Contacts

What's Possible

Testing your Plaid workflows

Authentication methods

Hosted URL Integration

Step 1. Integrate Plaid Hosted Link

Step 2. Create hosted URL

GenerateVerifiedExternalBankAccountLinkToken

Step 3. Get link status

AccountHolderProvisioning

Plaid SDK Integration

Step 1. Integrate Plaid Link

Step 2. Create link token

Step 3. Initialize Plaid Link

Step 4. Link external account with public token

ProvisionAccountHolder

Step 5. Get link status

AccountHolderProvisioning

Connect verified account with Plaid

Prerequisite: Set up your Plaid account

Step 1. Enable Plaid account for Highnote

Step 2. Create a Plaid link token

Step 3. Get Plaid's Highnote processor token

Step 4. Link external account with processor token

AddExternalBankAccountVerifiedThroughPlaid

Step 5. Test Plaid connections

Connect a non-verified account

AddNonVerifiedExternalUSFinancialBankAccount

List external accounts

ListAccountHolders

Disconnect external account

CloseExternalFinancialBankAccount