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: The customer connects their external bank account via Cybrid's Plaid account.
2. Plaid processor token: The customer connects their external bank account via the partner's Plaid account.
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 provide 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. 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 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 above to retrieve plaid_link_token using the GET /api/workflows/{guid} endpoint
• Use the plaid_link_token from above to initialize the Plaid Link SDK.
• Upon a successful connection in the Plaid Link SDK, capture the plaid_public_token and plaid_account_id.
• 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 above.

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 integrate with the Cybrid Platform. Partners must:

• Enable the Identity product with Plaid
• Enable the Modern Treasury processor in your Plaid environment
• Generate the 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, ensure the customer has sufficient balance (i.e. NSFs are the partner's responsibility)

With the above complete and after a customer has been created, 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. 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, you can create external bank accounts, which are exclusively for credit operations (funds can only be sent to these accounts).

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

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

Once the prerequisites are fulfilled, 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. 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
7. invalid_routing_number: The routing details specified are not correct.