Connect External Accounts

Account holders can connect external bank accounts to Highnote for making ACH funds transfers. Highnote has partnered with Plaid and Finicity as secure, NACHA-compliant options to verify and link external accounts.

Fund-in transfers into Highnote require external account verification.

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 via Plaid or Finicity.
• 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:

• ExternalFinancialBankAccount: Represents an account that is verified and can be used to fund in or fund out a payment.
• NonVerifiedExternalUSFinancialBankAccount: Represents an account that can only be used to fund out a payment.

Contact your Highnote sales representative to learn more about available Plaid products and pricing for your program.

The Highnote platform offers two ways for subscribers to securely integrate with Plaid's services:

• Connect verified account with Highnote: For subscribers who prefer to delegate their Plaid relationship to Highnote. In this model, Highnote works with Plaid on behalf of subscribers to securely verify end user (Highnote account holder) bank accounts.

• Connect verified account with Plaid: For subscribers who prefer a direct relationship with Plaid. In this model, subscribers use Plaid to authenticate end user (Highnote account holder) bank accounts in their applications and securely pass verification details to Highnote.

Delegating your Plaid relationship to Highnote reduces your compliance requirements because Highnote provides and manages a secure vault.

As a subscriber, you can simplify your Plaid integration by enabling Highnote to securely retrieve external account information on your behalf. With a persistent access_token, Highnote verifies end user bank accounts and then initiates and manages the ACH transfer for you.

To connect verified external accounts to Highnote:

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

Highnote requests the following information on your Plaid Onboarding form:

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

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

• Plaid Link configuration: Customizable or Plaid default
• SDKs you want to integrate: Web, iOS, Android, React Native, Mobile webview.
• SDK redirect_uri or package_name (which is the redirectUri used in Step 3):
  • Web SDK: Web SDK redirect URI
  • Apple iOS: Universal Link redirect URI
  • Android, React Native: Android package name

Note: 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

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

To initiate Plaid Link (in Step 4), you must first create a Highnote link_token. You'll use this token to generate a public_token in Plaid.

In the Test environment, Highnote provides you with a link_token that can be used in Plaid’s Sandbox environment to generate a public_token. Your organization will need to be configured by Highnote for the Plaid integration.

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

To initialize Plaid Link, use the link_token you received from Highnote (in Step 3) to generate a public_token in Plaid. Plaid Link provides a temporary public_token in the onSuccess callback.

The details for passing the link_token varies 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

Use 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.

Use the following query to lookup the status of linking an external bank account to the account holder.

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.

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

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

If a user has multiple bank accounts, the accounts array from Plaid may contain information from all of them. Highnote requires only one bank account. To ensure the accounts array always 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 tab, select the use cases you want to use with Highnote.

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.

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

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:

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

With a Finicity integration, account holders can connect verified external bank accounts 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 and it eliminates the need for you to store sensitive information from your account holder’s external bank accounts.

Before integrating with Finicity, you must sign up for an account and create an access token:

1. Sign up for Finicity API keys.
2. Once you have Finicity API keys, create a Finicity Access Token to onboard your account holders.
3. Once the Access Token is shared with Highnote, it is used to securely retrieve account and routing numbers from Finicity.

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

You can test 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 Finicity 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

Copy code snippet

Body (raw, JSON)

Copy code snippet

Sample response payload

Copy code snippet

With a Finicity Access Token, you can call the Highnote API with the following mappings to link an external bank account:

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

Use the following mutation to add an external bank account with Finicity:

Note: 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 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 following external account information:

• Routing number
• Account number
• Account type: Checking or savings

Optionally, a nickname can be assigned to the non-verified account for reference.

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

Note: The same mutation is used to disconnect verified and non-verified external bank accounts.

You can use the CloseExternalFinancialBankAccount to provide the following experiences for disconnecting an external account:

• 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

Note the following guidelines for disconnecting an external bank account:

• When the external bank account is disconnected, all scheduled payments associated with the external bank account will be canceled. 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 reconnect a verified bank account to their Highnote financial account.
• If the customer is disconnecting or reconnecting 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:

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