GuidesRecipesAPI ReferenceChangelog
Guides

Deposit Bank Accounts

What are deposit bank accounts for and how do I use them?

Deposit bank accounts are routable bank accounts that allow third-party Wire, ACH push, or RTP/FedNow transfers on and off the platform. The account includes complete routing details and beneficial owner information.

Deposit bank accounts can be created for either a bank or a customer; as a result, each deposit bank account is either linked to a bank-level or a customer platform fiat account. Funds deposited or withdrawn from a deposit bank account are reflected in the platform_balance and platform_available values of the linked fiat platform account. Deposit bank accounts do not hold funds directly.

Key points:

  • Currently, deposit bank accounts can only be created for US banks.
  • Only one deposit bank account can be created for each platform fiat account. In other words, if a bank or a customer has multiple fiat accounts, a unique deposit bank account can be created for each individual fiat account.
  • Transfers into a deposit bank account are never initiated by the Cybrid platform; they are always initiated externally.
ℹ️

ACH push microdeposits

Externally initiated ACH push microdeposits (such as those sent from external banks for account verification) will appear in the customer's deposit account history. These transactions can be identified by their small amounts (typically less than $2) and will be reflected in the account's balance and transaction history.

Deposit Bank Account Types

There are two types of deposit bank accounts. A main account, and a sub_account.

Main

Main accounts have a unique account_number, and can accept deposits as well as initiate withdrawals. Because there is a unique account number, a main account has an opening fee and a monthly maintenance fee:

  • One-time $1.00 fee to create
  • Recurring $0.50 fee to maintain / per month

When processing a withdrawal transfer from a main account, the recipient will see the main account's holder (counterparty) information, such as the legal name and address, on the transfer if the send_as_deposit_bank_account_guid is set.

To create a Main account, set the type to main, such as the following API request:

POST /api/deposit_bank_accounts

{
  "type": "main",
  "customer_guid": "customer_guid",
  "account_guid": "customer_fiat_account_guid"
}
{
  "created_at": "datetime",
  "updated_at": "datetime",
  "guid": "deposit_bank_account_guid",
  "type": "main",
  "bank_guid": "bank_guid",
  "customer_guid": "customer_guid",
  "account_guid": "customer_fiat_account_guid",
  "asset": "USD",
  "state": "created",
  "unique_memo_id": "unique_memo_id",
  "counterparty_name": "customer_legal_name",
  "counterparty_address": {
    "street": "123 Main St",
    "street2": null,
    "city": "New York",
    "subdivision": "NY",
    "postal_code": "10001",
    "country_code": "US"
  },
  "account_details": [
    {
      "account_number": "111222333"
    }
  ],
  "routing_details": [
    {
      "routing_number": "021000021",
      "routing_number_type": "ABA"
    }
  ],
  "labels": null
}

Sub-Account

Sub-accounts are used when you want to allow your customers to receive wires directly into their fiat account without needing to generate a unique deposit bank account for each (i.e., a main account). There are no fees for sub-accounts.

ℹ️

Sub-account restriction

Only a customer can have sub_account type deposit bank accounts.

A sub-account inherits the account_number and routing_number from the main account. When depositing funds (e.g. using a Wire transfer) to a sub-account, the customer must include the unique_memo_id and the platform will automatically reconcile the deposit into the customer's fiat account instead of the bank's fiat account. If the customer forgets to include the unique_memo_id, or if they use an incorrect memo, the deposit will still complete successfully, but the funds will reflect on the partner (bank-level) fiat account instead. You will then need to initiate a book transfer to transfer the funds to the customer's fiat account.

To create a sub-account, set the type to sub_account and set the parent_deposit_bank_account_guid to your partner (bank-level) deposit bank account (of type main) or the same customer deposit bank account (of type main), such as the following API request:

POST /api/deposit_bank_accounts

{
  "type": "sub_account",
  "customer_guid": "customer_guid",
  "account_guid": "customer_fiat_account_guid",
  "parent_deposit_bank_account_guid": "main_deposit_bank_account_guid"
}
{
  "created_at": "datetime",
  "updated_at": "datetime",
  "guid": "deposit_bank_account_guid",
  "type": "sub_account",
  "bank_guid": "bank_guid",
  "customer_guid": "customer_guid",
  "account_guid": "customer_fiat_account_guid",
  "asset": "USD",
  "state": "created",
  "unique_memo_id": "unique_memo_id",
  "counterparty_name": "customer_legal_name",
  "counterparty_address": {
    "street": "123 Main St",
    "street2": null,
    "city": "New York",
    "subdivision": "NY",
    "postal_code": "10001",
    "country_code": "US"
  },
  "account_details": [
    {
      "account_number": "111222333"
    }
  ],
  "routing_details": [
    {
      "routing_number": "021000021",
      "routing_number_type": "ABA"
    }
  ],
  "parent_deposit_bank_account_guid": "parent_deposit_bank_account_guid",
  "labels": null
}

Beneficiary Information

For type main deposit bank accounts, the platform uses the PII data collected during KYC for the beneficiary information on the account, which is displayed in counterparty_name and counterparty_address.

For type sub_account deposit bank accounts, the beneficiary information is the information associated with the parent main account.

Send as a Deposit Bank Account

To set the customer's name and address as the sender information (instead of the partner's) on a withdrawal fiat transfer, the customer must have a main deposit bank account. Include that account's identifier in the send_as_deposit_bank_account_guid field:

⚠️

RTP sender name display

For RTP (Real Time Payment) withdrawals, even if you set send_as_deposit_bank_account_guid, most recipient banks will only display the originator (Cybrid) on the recipient's statement. This is due to industry specifications and recipient bank practices, and it is not possible to guarantee that your company name will appear in the transaction description for RTP withdrawals. This differs from ACH and Wire withdrawals, where the company name can typically be displayed as intended.

POST /api/transfers

{
  "quote_guid": "quote_guid",
  "transfer_type": "funding",
  "customer_guid": "customer_guid",
  "external_bank_account_guid": "customer_external_bank_account_guid",
  "payment_rail": "rtp",
  "source_participants": [
    {
      "type": "customer",
      "amount": 5000,
      "guid": "customer_guid"
    }
  ],
  "destination_participants": [
    {
      "type": "customer",
      "amount": 5000,
      "guid": "customer_guid"
    }
  ],
  "send_as_deposit_bank_account_guid": "customer_deposit_bank_account"
}

Bank Name in Deposit Bank Account APIs (Sandbox vs Production)

When using the GET /api/deposit_bank_accounts/{guid} endpoint, the response includes a bank_guid but does not directly provide the bank's name. To retrieve the bank name, you must make a separate request to the GET /api/banks/{guid} endpoint using the bank_guid value.

Sandbox Environment:

  • In the sandbox, the bank object represents a simulated or internal test bank, not an actual external financial institution.
  • The name field (e.g., "Example Bank") is tied to your organization configuration and does not reflect the real-world bank associated with the routing number.

Production Environment:

  • In production, the bank object and its name field may represent the actual financial institution, depending on your integration and configuration.

Keep this distinction in mind when testing integrations that display bank names.

Updated 18 days ago