Home / Issuing / Transfer Funds

Connect External Accounts

Overview

External bank accounts can be connected to an Account Holder as a funding source. These accounts may be used to transfer funds to or from a Financial Account via ACH.

Highnote has partnered with Plaid and Finicity as secure, NACHA compliant options for your Account Holders to verify and link their external accounts. Account Holders can connect their account by invoking Plaid or Finicity’s widget from your app or website. Once linked, Account Holders can seamlessly transfer funds via ACH between the Highnote Financial Account and the external bank account.

There are two methods for transferring funds using an external account:

  • Fund In: Refers to the transfer of funds from an external account (source account) to a Highnote Financial Account (destination account). Fund In transfers require external account verification via Plaid or Finicity.
  • Fund Out: Refers to the transfer of funds from a Highnote Financial Account (source account) to an external account (destination account). Fund Out transfers do not require verification of the external account and can only be initiated on Card Products with a cash deposit (e.g. Debit Card, Secured Credit Card).

There are two possible types of ExternalFinancialAccounts referenced in the Highnote API:

  • NonVerifiedExternalUSFinancialBankAccount: Indicates the account can only be used to fund out a payment.
  • ExternalFinancialBankAccount: Indicates the account is verified and may be used to fund in or fund out a payment.

Connect Verified Account via Plaid

Plaid and Highnote have partnered to provide a simple way for your Account Holders to fund their accounts or make payments on your platform. You can use Plaid's drop-in module on your app or website to provide an easy interface for Account Holders to connect their external accounts with. Once an external bank account is verified, you can use Highnote to transfer money between the Account Holder’s external bank account and their Financial Account.

This integration was built with security in mind and it eliminates the need for you to store sensitive information from your Account Holder’s external bank accounts.

Set Up Your Plaid Account

The accounts array from Plaid contains information about bank accounts associated with the credentials entered by the user. If the user has multiple bank accounts, the accounts array may contain information from multiple accounts.

Highnote requires only one bank account. To have the customer select a single account to link, set Account Select to "enabled for one account" in the Plaid Developer Dashboard. When this setting is selected, the accounts array will always contain exactly one account.

Set Up Your Plaid Account

  1. To get started, sign up for Plaid API keys.
  2. You'll need to create an account at Plaid and integrate with Plaid Link to create a link_token. For information on integrating with Plaid Link, Plaid's Documentation.
  3. Once Plaid is integrated, your customers can use the drop-in module on your app or website to connect their external bank accounts.
  4. Once a customer has selected and verified their external bank account, Plaid will provide you with Highnote’s processor_token. You'll send this token to Highnote, and we will use it to securely retrieve account and routing numbers from Plaid.

Test Plaid Connections

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 Verified Account via Finicity

Finicity and Highnote have partnered to provide a simple way for your Account Holders to fund or make payments to their accounts on your platform. Your Account Holders can connect their external bank accounts from Finicity within your app or website. Once an external bank account is verified, you can use Highnote to transfer money between the Account Holder’s external bank account and their Financial Account.

This integration was built with security in mind, as it eliminates the need for you to store sensitive information from your Account Holder’s external bank accounts.

Set Up Your Finicity Account

To get started, sign up for Finicity API keys.

Once you have Finicity API Keys, you create a Finicity Access Token to onboard your Account Holders and have them select and verify their external bank account to be used. Once the Access Token is shared with Highnote, we will use this Access Token to securely retrieve account and routing numbers from Finicity.

Test Finicity Connections

You can test the Finicity API keys in a live environment, using their preset test profiles to test for all scenarios. Finicity has also set up mock FinBanks to simulate testing against live Financial Institutions.

In order to proceed with testing, you would need to first set up your environment and follow the instructions.

  1. Generate Finicity-App-Token
  2. Create a test customer in Finicity's System
  3. Generate Connect URL and simulate customer linking bank accounts to Finicity
  4. Refresh customer accounts
  5. Generate 3rd party api access token information to send to Highnote: POST request to https://api.finicity.com/aggregation/v1/partners/accessKey

Headers:

Accept: application/json,
Content-Type: application/json,
Finicity-App-Token: <app-token-from-step-0>,
Finicity-App-Key: <app-key-from-developer-portal>

Body (raw, JSON):

{
  "customerId": "<customer-id-from-step-1>",
  "partnerId": "<subscriber-partner-id-from-developer-portal>",
  "thirdPartyPartnerId": "<Highnote-partner-id>",
  "products": [
    {
      "product": "moneyTransferDetails",
      "payorId": "<subscriber-partner-id-from-developer-portal>",
      "maxCalls": 1000,
      "accountId": "<account-id-from-step-3>",
      "accessPeriod": {
        "type": "timeframe",
        "startTime": "2022-03-10T06:06:20Z",
        "endTime": "2023-03-10T06:06:20Z"
      }
    },
    {
      "product": "availableBalanceLive",
      "payorId": "<subscriber-partner-id-from-developer-portal>",
      "maxCalls": 1000,
      "accountId": "<account-id-from-step-3>",
      "accessPeriod": {
        "type": "timeframe",
        "startTime": "2022-03-10T06:06:20Z",
        "endTime": "2023-03-10T06:06:20Z"
      }
    },
    {
      "product": "accountOwner",
      "payorId": "<subscriber-partner-id-from-developer-portal>",
      "maxCalls": 1000,
      "accountId": "<account-id-from-step-3>",
      "accessPeriod": {
        "type": "timeframe",
        "startTime": "2022-03-10T06:06:20Z",
        "endTime": "2023-03-10T06:06:20Z"
      }
    }
  ]
}

Sample Response Payload:

{
  "data": [
    {
      "receipt": {
        "profile": 3,
        "version": "1",
        "receiptId": "cr_vYdb1DGoLpI9opOqwkkfBy464SmIDd",
        "receiptVersion": "1",
        "customerId": "5543088633794259024",
        "partnerId": 2445583993914,
        "products": [
          {
            "product": "moneyTransferDetails",
            "accountId": "8977412844634022494",
            "accessPeriod": {
              "type": "timeframe",
              "startTime": "2022-03-10T06:06:20Z",
              "endTime": "2023-03-10T06:06:20Z"
            }
          },
          {
            "product": "availableBalanceLive",
            "accountId": "1045023535892401594",
            "accessPeriod": {
              "type": "timeframe",
              "startTime": "2022-03-10T06:06:20Z",
              "endTime": "2023-03-10T06:06:20Z"
            }
          },
          {
            "product": "accountOwner",
            "accountId": "5200183909259568542",
            "accessPeriod": {
              "type": "timeframe",
              "startTime": "2022-03-10T06:06:20Z",
              "endTime": "2023-03-10T06:06:20Z"
            }
          }
        ]
      }
    }
  ]
}

Link Account Holder’s External Bank Account

Now that you have a Finicity Access Token, you can call the Highnote GraphQL API with the following mappings to link your Account Holders External Bank Account:

  • moneyTransferDetails -> ACH_DETAILS
  • availableBalanceLive -> CURRENT_BALANCE
  • accountOwner -> ACH_OWNER_DETAILS

Set Up Your Finicity Account

  1. To get started, sign up for Finicity API keys.
  2. Once you have Finicity API Keys, create a Finicity Access Token to onboard your Account Holders and have them select and verify their external bank account.
  3. Once the Access Token is shared with Highnote, we will use the Access Token to securely retrieve account and routing numbers from Finicity.

Test Finicity Connections

Note: Highnote's Finicity partner ID is 2445583993914. When testing, input this value as the thirdPartyPartnerId.

You can test the Finicity API keys in a live environment, using their preset test profiles to test for all scenarios. Finicity has also set up mock FinBanks to simulate testing against live Financial Institutions.

To begin testing, you must first set up your test environment. After setting up your test environment, refer to the following steps:

  1. Generate Finicity-App-Token
  2. Create a test customer in Finicity's System
  3. Generate Connect URL and simulate customer linking bank accounts to Finicity
  4. Refresh customer accounts
  5. Generate 3rd party API access token information to send to Highnote. Use the following POST request to https://api.finicity.com/aggregation/v1/partners/accessKey:

Headers:

Accept: application/json,
Content-Type: application/json,
Finicity-App-Token: <app-token-from-step-0>,
Finicity-App-Key: <app-key-from-developer-portal>

Body (raw, JSON):

{
  "customerId": "<customer-id-from-step-1>",
  "partnerId": "<subscriber-partner-id-from-developer-portal>",
  "thirdPartyPartnerId": "2445583993914",
  "products": [
    {
      "product": "moneyTransferDetails",
      "payorId": "<subscriber-partner-id-from-developer-portal>",
      "maxCalls": 1000,
      "accountId": "<account-id-from-step-3>",
      "accessPeriod": {
        "type": "timeframe",
        "startTime": "2022-03-10T06:06:20Z",
        "endTime": "2023-03-10T06:06:20Z"
      }
    },
    {
      "product": "availableBalanceLive",
      "payorId": "<subscriber-partner-id-from-developer-portal>",
      "maxCalls": 1000,
      "accountId": "<account-id-from-step-3>",
      "accessPeriod": {
        "type": "timeframe",
        "startTime": "2022-03-10T06:06:20Z",
        "endTime": "2023-03-10T06:06:20Z"
      }
    },
    {
      "product": "accountOwner",
      "payorId": "<subscriber-partner-id-from-developer-portal>",
      "maxCalls": 1000,
      "accountId": "<account-id-from-step-3>",
      "accessPeriod": {
        "type": "timeframe",
        "startTime": "2022-03-10T06:06:20Z",
        "endTime": "2023-03-10T06:06:20Z"
      }
    }
  ]
}

Sample Response Payload:

{
  "data": [
    {
      "receipt": {
        "profile": 3,
        "version": "1",
        "receiptId": "cr_vYdb1DGoLpI9opOqwkkfBy464SmIDd",
        "receiptVersion": "1",
        "customerId": "5543088633794259024",
        "partnerId": 2445583993914,
        "products": [
          {
            "product": "moneyTransferDetails",
            "accountId": "8977412844634022494",
            "accessPeriod": {
              "type": "timeframe",
              "startTime": "2022-03-10T06:06:20Z",
              "endTime": "2023-03-10T06:06:20Z"
            }
          },
          {
            "product": "availableBalanceLive",
            "accountId": "1045023535892401594",
            "accessPeriod": {
              "type": "timeframe",
              "startTime": "2022-03-10T06:06:20Z",
              "endTime": "2023-03-10T06:06:20Z"
            }
          },
          {
            "product": "accountOwner",
            "accountId": "5200183909259568542",
            "accessPeriod": {
              "type": "timeframe",
              "startTime": "2022-03-10T06:06:20Z",
              "endTime": "2023-03-10T06:06:20Z"
            }
          }
        ]
      }
    }
  ]
}

Simulate Connecting a Verified Account

Warning: The Highnote test environment allows you to freely explore the platform features and functionality. It is intended for experimenting, building integrations, and training your team.

To ensure the security of your real-world data, please refrain from entering production data into the test environment. Production data includes sensitive information like customer details, financial data, or personally identifiable information (PII).

Use only dummy or test data explicitly created for testing purposes in the test environment.

For testing purposes, you can simulate connecting an external bank account via Plaid or Finicity by calling the AddExternalBankAccountVerifiedThroughPlaid or AddExternalBankAccountVerifiedThroughFinicity mutations and providing Plaid processor_token or Finicity receiptId values.

This simulation triggers the following success or failure responses you may receive in production:

Processor Token Simulation ValueDescription
processor-token-not-foundCould not find matching processor token.
processor-token-no-ach-account-numberProcessor returned invalid account for given token. Occurs when account number is not available in response.
processor-token-no-routing-account-numberProcessor returned invalid routing number for given token. Occurs when routing number is not available in response.
processor-token-wrong-sub-typeProcessor returned invalid account sub type. Supported types are CHECKING and SAVINGS.
processor-token-wrong-currency-codeProcessor returned invalid currency code. Supported type is USD.
processor-token-wrong-length-account-numberProcessor returned invalid account number for given token. Length of account number is more than 17.
processor-token-wrong-length-routing-numberProcessor returned invalid routing number for given token. Length of routing number is more than 9.
processor-token-non-digit-routing-numberProcessor returned invalid routing number for given token. Routing number contains characters other than digits.
processor-token-successSuccessful connection.
processor-token-item-login-requiredThe login details of this item have changed (credentials, MFA, or required user action), and a user login is required to update this information.
processor-token-institution-downThis institution is not currently responding to this request. Please try again soon.

Connect Non-Verified Account

A bank account number can be de-tokenized if it has been added using the addNonVerifiedExternalFinancialBankAccount mutation. For bank accounts connected and verified via the addExternalBankAccountFromToken mutation, the bank account number cannot be de-tokenized for security purposes.

External bank accounts that have not been verified by a third-party service such as Plaid or Finicity are considered to be "Non-Verified". Funds may only be sent to a Non-Verified External Bank Account from a Highnote Financial Account. Non-Verified External Bank Accounts may not be used to move funds into Highnote.

The most common use case for Non-Verified External Bank Accounts is to return funds to an Account Holder in the event of account closure.

When connecting an external bank account, your Account Holder must provide the external account’s routing number, account number, and account type (e.g. checking or savings). A nickname can be assigned to the external account for reference to future payments. The added bank account will be connected to the Account Holder, and can be found by searching for the Account Holder’s linked bank accounts.

Use the following mutation to add a Non-Verified External Bank Account:

Disconnect External Account

If your customer wishes to disconnect an external bank account, you can provide an interface for your customer to disconnect or have your organization's support agents remove the account holder’s external bank account using the Highnote dashboard. The same mutation is used to disconnect verified and non-verified external bank accounts.

When the external bank account is disconnected, all scheduled payments associated with the external bank account will be cancelled. If the Highnote financial account associated with the external bank account has a pending payment, the account can't be disconnected until the pending payment(s) settles.

Once disconnected, the customer will need to re-verify their identity to add a verified bank account to their Highnote financial account. If the customer is disconnecting or re-connecting a non-verified bank account, they do not need to re-verify their identity.

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

List External Accounts

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

Provide Feedback

Was this content helpful?