Connect External Accounts

Overview

External bank accounts may 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 options for your Account Holders to verify and link their external accounts. The 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.

Fund In: To transfer funds in to a Highnote Financial Account (Destination Account), the bank account details of the external account (Source Account) must be verified per the NACHA guidelines. Today, Highnote supports Bank account verification via Plaid or Finicity.

Fund Out: For transferring funds from a Highnote Financial Account to an external bank account, the bank account does not need to be verified, but an external verified account may be used. Fund-out transfers can only be initiated on Products with a cash deposit (e.g. Debit Card, Secured Credit Card).

The type name of NonVerifiedExternalUSFinancialBankAccount on the external financial account will indicate that the account can only be used to fund out a payment. ExternalFinancialBankAccount type name will indicate that the account 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 or make payments to their accounts on your platform. Your Account Holders can connect their external bank accounts from Plaid's drop-in module 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 Plaid Account

To get started sign up for Plaid API keys.

You'll need to create an account at Plaid and integrate with Plaid Link to create a link_token by following the instructions in Plaid's Documentation. Once your customer has selected and verified the external bank account they’ll use, 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.

Note: The accounts array from Plaid will contain information about bank accounts associated with the credentials entered by the user, and may contain multiple accounts if the user has more than one bank account at the institution. Highnote requires a single bank account be provided. 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.

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

Link Account Holder’s External Bank Account

Once you have received the processor_token from Plaid, you’ll provide this token to Highnote. Highnote will then retrieve the account number, routing number, and account type from Plaid and link the information to the associated Account Holder for future payment usage.

If the response includes a Processor Token related error, you should obtain a new processor_token from Plaid and reattempt adding the external bank account. You should use the error response to resolve the issue with Plaid. Your customer may need to resubmit their bank account credentials in order for you to retrieve a new processor_token.

Please see Plaid's documentation on errors for a comprehensive list of possible Plaid related errors.

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.

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

Simulate Connecting a Verified External Bank Account

The Test Environment does not call Plaid or Finicity when connecting an external bank account.

When testing, 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 which trigger the success or failure responses you may receive in production.

Processor Token Simulate 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 External Bank Accounts to Fund Out

Based on your Product setup, your Account Holders may be able to transfer Funds Out of their Highnote Financial Account to an external account. Since transfers are initiated by the Account Holder from their Financial Account to an external account, the ownership of the external account does not need to be verified by providers such as Plaid. However, funds can only be sent to a non-verified external account; funds cannot be pulled from a non-verified external account.

When connecting an external bank account, your Account Holder will need to 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.

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

Errors

Common errors when linking a non-verified external bank account.

FieldInput ExampleCodeDescription
routingNumbernullNON_NULL_INPUT_REQUIREDThe field is a required input
routingNumber1234MIN_LENGTH_REACHEDlength must be greater than or equal to 9 characters
routingNumber123456789123456789MAX_LENGTH_REACHEDlength must be less than or equal 9 characters
routingNumber" "NON_EMPTY_INPUT_REQUIREDA non empty input is required
routingNumber111010025INVALID_US_BANK_ROUTING_NUMBERRouting number provided is not a valid US Routing Number
accountNumbernullNON_NULL_INPUT_REQUIREDThe field is a required input
accountNumber1234MIN_LENGTH_REACHEDlength must be greater than or equal to 5 characters
accountNumber123456789123456789MAX_LENGTH_REACHEDlength must be less than or equal 17 characters
name NON_EMPTY_INPUT_REQUIREDA non empty input is required
accountHolderId"stringexceeding255chars"MAX_LENGTH_REACHEDvalue cannot exceed 255
accountHolderIdnullNON_NULL_INPUT_REQUIREDThe field is a required input
accountHolderId NON_EMPTY_INPUT_REQUIREDA non empty input is required
bankAccountTypeCHEQUEINGINVALID_INPUTThe input supplied is invalid

Example Error Payload

Connecting Non-Verified External Account Error
{
  "path": ["input", "routingNumber"],
  "code": "NON_NULL_INPUT_REQUIRED",
  "description": "This is a required field"
}

List Person’s External Bank Accounts

You can view and present a Person Account Holder’s external bank accounts for future payments.

List Business' External Bank Accounts

You can view and present a Business Account Holder’s external bank accounts for future payments.

Find External Bank Account Details

You can also find the details of an Account Holder’s external bank accounts, such as account number and routing number.

Find External Bank Account Details with Client Token

You can obtain the restricted details on an ExternalFinancialBankAccount using the External Bank Account Client Token.

Disconnect External Bank Accounts

Only Verified External Bank Accounts linked via Plaid may be disconnected at this time.

If your customer wishes to disconnect an external bank account, your customer or support agents (via the Dashboard) can remove the Account Holder’s external bank account.

All scheduled payments associated with the external bank account will be cancelled when the external bank account is deleted. If the Financial Account has a pending payment from the external bank account, the account cannot be removed until the pending payment(s) settles.

Once removed, the customer will need to re-verify their identity to add the bank account to their Account again.

Provide Feedback

Was this content helpful?