Home / Issuing / Transfer Funds
External bank accounts can be connected to an account holder financial account as a funding source. These accounts transfer funds via ACH.
Highnote has partnered with Plaid and Finicity as secure, NACHA-compliant options to verify and link external accounts. Account holders can connect their external accounts to Highnote by invoking Plaid or Finicity’s widget from your app or website. Once linked, account holders can seamlessly transfer funds via ACH between their Highnote financial account and external bank account.
There are two methods for transferring funds using an external account:
There are two types of ExternalFinancialAccounts
referenced in the [Highnote API]((/docs/reference/union/ExternalFinancialAccount):
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.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. Highnote's Plaid 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.
Note: 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.
To use Plaid, you must first create a Plaid account. Use the following steps to set up your Plaid account before integrating with Highnote:
link_token
. For information on integrating with Plaid Link, see Plaid's Documentation.processor_token
. You'll send this token to Highnote, and we will use it to securely retrieve account and routing numbers from 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:
Once you have received the processor_token
from Plaid, you’ll provide this token to Highnote using the AddExternalBankAccountVerifiedThroughPlaid
mutation. 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, you should obtain 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 Plaid's error documentation for a comprehensive list of possible Plaid-related errors.
Use the following mutation to add an external bank account using Plaid:
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:
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:
https://api.finicity.com/aggregation/v1/partners/accessKey
: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:
Warning: The Highnote test environment lets you explore the platform's features and functionality. It is intended for experimenting, building integrations, and training your team.
To ensure the security of your real-world data, please do not enter production data in 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.
You can use the Highnote test environment to simulate connecting verified external accounts with Plaid and Finicity. To use the simulation, you must use specific simulation values for the following fields in the simulation mutation:
processor_token
receiptId
Using this simulation triggers the following success or failure responses you may receive in production:
Response Simulation Value | Description |
---|---|
processor-token-not-found | Could not find matching processor token. |
processor-token-no-ach-account-number | Processor returned invalid account for given token. Occurs when account number is not available in response. |
processor-token-no-routing-account-number | Processor returned invalid routing number for given token. Occurs when routing number is not available in response. |
processor-token-wrong-sub-type | Processor returned invalid account sub type. Supported types are CHECKING and SAVINGS . |
processor-token-wrong-currency-code | Processor returned invalid currency code. Supported type is USD . |
processor-token-wrong-length-account-number | Processor returned invalid account number for given token. Length of account number is more than 17. |
processor-token-wrong-length-routing-number | Processor returned invalid routing number for given token. Length of routing number is more than 9. |
processor-token-non-digit-routing-number | Processor returned invalid routing number for given token. Routing number contains characters other than digits. |
processor-token-success | Successful connection. |
processor-token-item-login-required | The 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-down | This institution is not currently responding to this request. Please try again soon. |
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:
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:
Note the following guidelines for disconnecting an external bank account:
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: