Add Bank Accounts

Learn how to create fiat external bank accounts for individual and business customers

Choosing your external bank account type

There are three types of external bank accounts:

1. Plaid: Partners connect their customer's bank accounts via Cybrid's Plaid Link.
2. Plaid processor token: Partners connect their customer's bank accounts via their own Plaid Link.
3. Counterparty external bank accounts: The customer provides routing details for a third party bank account.

Type #1: Plaid

Cybrid offers the convenience of leveraging the Cybrid Platform Plaid account so partners do not have to acquire their own Plaid account.

📘

Tip: The Cybrid web SDK provides a UI component to handle connecting external bank accounts via Plaid that handles the sequence of API requests detailed below for you.

As an alternative to Cybrid's web SDK, you can choose to programmatically drive the process through our APIs and your implementation of the Plaid Link SDK (see Plaid's documentation for more details on Plaid Link). This approach provides greater flexibility and customization options for your integration with the Cybrid Platform.

Here is the step-by-step process for programmatically driving the external bank account connect process with Cybrid's API and the Plaid Link SDK:

• Create a new workflow with kind:"link_token_create" via the POST /api/workflows endpoint.
• Use the workflow guid from the response to retrieve a plaid_link_token using the GET /api/workflows/{guid} endpoint.
• Use the plaid_link_token from the response to initialize the Plaid Link SDK.
• Guide your customer to connect their bank account via Plaid Link
• Upon your customer successfully connecting their bank account via Plaid Link, capture the plaid_public_token and plaid_account_id from the accept callback from Plaid.
• Create an external bank account for the customer via the POST /api/external_bank_accounts endpoint using the plaid_public_token and plaid_account_id from the accept callback.

An example POST external bank account request body is below:

{
  "name": "<insert descriptive account name>",
  "account_kind": "plaid",
  "customer_guid": "<insert customer_guid>",
  "asset": "USD",
  "plaid_public_token": "<insert plaid_public_token>",
  "plaid_account_id": "<insert plaid_account_id>"
}

Type #2: Plaid processor token

Partners that prefer, or already have, their own Plaid account may also connect their customers' bank accounts with the Cybrid Platform.

In order for bank accounts connected via a partner's Plaid account to be compatible with the Cybrid Platform, the partner must configure the following in their Plaid instance:

• Enable the Identity product
• Enable the Modern Treasury processor

Moreover, when connecting customer bank accounts via a partner's Plaid, you must also:

• Generate a plaid_processor_token with modern_treasury as the provider.
• When creating funding transfers on the platform where you are pulling funds from the customer's account, also ensure that the customer has sufficient balance prior to debiting the customer's account.

🚧

Note: It is critically important for partners to check their customers' balance prior to debiting their account. Failure to do so will result in a higher incident of returns for non-sufficient funds.

With the above complete and after a customer has been created and KYC verified, you can then create an external bank account for the customer via the POST /api/external_bank_accounts endpoint.

{
  "name": "<insert descriptive account name>",
  "account_kind": "plaid_processor_token",
  "customer_guid": "<insert customer_guid>",
  "asset": "USD",
  "plaid_processor_token": "<insert plaid_processor_token>",
  "plaid_institution_id": "<insert plaid_institution_id>",
  "plaid_account_mask": "<insert plaid_account_mask>",
  "plaid_account_name": "<insert plaid_account_name>"
}

Type #3: Counterparty external bank accounts

📘

This feature is disabled by default in Production. It must be enabled on a per-bank basis. To enable it, please contact Cybrid Support.

The Cybrid platform allows customers and partners to set up external bank accounts for counterparties, enabling third-party payouts. By providing the necessary bank routing details and beneficiary information, you can create external bank accounts using raw routing details, which are exclusively for credit operations (i.e., funds can only be sent to these accounts and cannot be withdrawn).

Before a counterparty external bank account can be created the following steps need to be completed:

• The counterparty has been created using the POST /counterparties endpoint; and,
• The counterparty’s identity has been verified using POST /identity_verifications endpoint.

Once these steps are completed, you can create an external bank account for the counterparty using the POST /api/external_bank_accounts endpoint:

{
  "name": "<insert descriptive account name>",
  "account_kind": "raw_routing_details",
  "customer_guid": "<insert customer_guid>",
  "counterparty_guid": "<insert counterparty guid>",
  "asset": "USD",
  "counterparty_bank_account": {
    "routing_number_type": "<insert routing number type>",
    "routing_number": "<insert routing number>",
    "account_number": "<insert account number>"
  },
}

Possible failure codes returned on create and how to handle them

There are various errors that can occur when attempting to add an ExternalBankAccount to the Cybrid Platform using either the "account_kind": "plaid" or the "account_kind": "plaid_processor_token" methods. Below is a description of each and how the caller should handle them:

1. invalid_routing_number: The account details associated with the account are invalid for routing. Create will always fail for this account.
2. plaid_multiple_accounts: The Plaid token or Plaid Processor Token supplied is associated with multiple bank accounts. Tokens associated with only a single account are accepted by the Cybrid Platform. If the customer wants to connect multiple accounts to the platform they must do so one at a time. Create will always fail for the supplied token.
3. plaid_processor_token: The provided Plaid Processor Token could not be used and is, possibly, invalid. Create will always fail for the supplied token.
4. create_failed: When attempting to use the supplied Plaid Processor Token, the bank account and account holder records could not be successfully created. This is most likely a transient failure and the caller should attempt to create the ExternalBankAccount again with this token. If the problem persists, the Plaid Processor Token should be refreshed by the caller before attempting to create the account again.
5. duplicate: The associated account to the supplied Plaid token or Plaid Processor Token already exists for the customer/ bank. Create will always fail for the supplied token.
6. unverified_counterparty: The counterparty needs to be verified before creating an counterparty external bank account