Fund via Plaid-Connected Bank Account

This guide walks you through funding a customer's fiat account from their Plaid-connected
external bank account.

Prerequisites

Before you begin, ensure you have:

• a customer already created and verified;
• a fiat account created for the customer; and,
• a Plaid-connected external bank account linked to the customer. See
  Add Customer External Bank Accounts.

Overview

The Plaid funding process involves three main steps:

1. Create a funding quote
2. Execute a transfer with the customer's external_bank_account_guid
3. Monitor the transfer until it reaches the completed state

Step 1: Create a funding quote

Create a quote via POST /api/quotes:

{
  "product_type": "funding",
  "customer_guid": "customer_guid",
  "asset": "USD",
  "side": "deposit",
  "deliver_amount": 10000
}

⚠️

Base units

The deliver_amount is in the base units of the currency. In the example above, 10,000 =
10,000 cents = $100.00 USD. Call GET /api/assets to get the number of base decimals for a
currency.

ℹ️

deliver_amount vs receive_amount

deliver_amount fixes what you send; fees come out of what the recipient gets.
receive_amount fixes what the recipient gets; you pay fees on top. See
Create and execute a trade
for the canonical explanation.

Set asset to USD, side to deposit, and deliver_amount to the desired amount. Once you
have your quote guid, proceed to the transfers API.

Step 2: Execute the transfer

You need the customer's external_bank_account_guid for this step. Retrieve it by calling
GET /api/external_bank_accounts with the customer's guid.

Create a transfer via POST /api/transfers with transfer_type set to funding, the quote
guid, and the external_bank_account_guid:

{
  "quote_guid": "quote_guid",
  "transfer_type": "funding",
  "external_bank_account_guid": "external_bank_account_guid",
  "payment_rail": "ach",
  "source_participants": [
    {
      "type": "customer",
      "guid": "customer_guid",
      "amount": 10000
    }
  ],
  "destination_participants": [
    {
      "type": "customer",
      "guid": "customer_guid",
      "amount": 10000
    }
  ]
}

ℹ️

Multiple fiat accounts

This example omits fiat_account_guid because it assumes one fiat account per asset. If the
customer or bank is configured with multiple fiat accounts for the asset, you must include
fiat_account_guid. See
Specify a fiat account.

⚠️

Sandbox limit

External Bank Accounts with account_kind=plaid are limited to $100.00 per funding transfer in sandbox.
Transfers exceeding $100.00 will fail. You can perform an unlimited number of transfers up to
$100.00.

ℹ️

Sandbox testing

The expected_state field is only available in sandbox to force specific transfer outcomes. Add
"expected_state": "pending" to the transfer request body to test state handling.

Payment rails

The Cybrid Platform defaults all USD transfers to same-day ACH ("payment_rail": "ach") and all CAD
transfers to EFT ("payment_rail": "eft").

Accounts can be funded using other payment rails — see
Fund via Deposit Bank Account.

Step 3: Monitor the transfer

Transfers are created asynchronously. Monitor the transfer until it reaches the completed state.

Settlement times depend on the payment_rail selected. For example, an ACH transfer requested at
4pm on a business day may not complete until 4pm the next business day. See
Fiat Transfer Settlement
for details.

Monitor transfer state by querying GET /api/transfers/{transfer_guid}, or register for
webhooks to receive automatic notifications on state
changes.

After creation, the transfer state is pending and progresses to completed when the fiat
settles.

Cancel a transfer

Transfers can only be cancelled between posting and bank execution — a small time window. No
API endpoint is available for partner-initiated cancellation.

Contact Cybrid support to request a transfer cancellation.

Handle Plaid errors

Creating a funding transfer using an External Bank Account of "account_kind": "plaid" or
"account_kind": "plaid_processor_token" can produce several errors.

The Cybrid Platform informs the caller of errors or required actions when using Plaid-connected
bank accounts.

Depending on the error received from Plaid, the associated External Bank Account for a transfer can be:

1. Put into a refresh_required state. This occurs when the customer must re-authenticate to their bank
   account via Plaid. When this does occur the partner must put their customer through a flow where Plaid
   Link is initialized in update mode. See the guide
   Refresh External Bank Accounts. The
   associated External Bank Account cannot be used until the account is re-authorized.
2. Put into a deleting and eventually deleted state. This occurs when Plaid has lost access to the
   customer's account completely or the customer has not granted sufficient permissions to Plaid to
   access their account. When this does occur the partner must instruct the customer to connect a different
   bank account via Plaid or to grant the required permissions to Plaid while interacting with Plaid Link.

Failure codes

When a funding transfer fails, the transfer state is failed with a failure_code.

Platform errors

Plaid errors

Troubleshooting non_sufficient_funds errors

If a transfer fails with a non_sufficient_funds error but the customer confirms there are sufficient funds in their
account, the cached Plaid balance may be stale. Force a live balance refresh to confirm whether the cached value was
out of date — see Check an external bank account balance.

Compare the refreshed balance to the transfer amount. If the issue persists after refreshing, review your API request
and response logs for the transfer attempt, including any error codes or messages. If the problem continues, contact
support with detailed logs and request IDs for further investigation.

Check an external bank account balance

Retrieve a Plaid-connected external bank account's balance by calling
GET /api/external_bank_accounts/{external_bank_account_guid} with include_balances=true.

Cached vs live balances

By default, include_balances=true returns the cached balance, which may be stale. Add
force_balance_refresh=true to bypass the cache and pull the live balance directly from the customer's financial
institution through Plaid at request time:

GET /api/external_bank_accounts/{external_bank_account_guid}?include_balances=true&force_balance_refresh=true

The response includes a balance_updated_at timestamp indicating how fresh the returned balance is. The balances
object contains available (funds usable now) and current (including pending transactions), both in the base units
of the account's currency (for example, cents for USD).

When to force a refresh

Use force_balance_refresh=true only when you need the most up-to-date balance — for example, when
investigating a non_sufficient_funds failure that the customer disputes, to confirm whether the
cached balance was stale.

For routine or repeated balance displays, rely on the cached balance (include_balances=true without
force_balance_refresh).

⚠️

Use forced refreshes sparingly

Do not poll this endpoint with force_balance_refresh=true. Each forced refresh makes a live call to the financial
institution, which is slower and more costly than reading the cached balance.

Performance and limits

Because a forced refresh waits on a live Plaid call to the financial institution, it is noticeably slower than a
standard read and is subject to Plaid's rate limits. Set a generous client-side timeout and avoid blocking a
user-facing flow synchronously on the response. Setting include_pii=true adds similar latency, because it triggers an
additional third-party lookup.

Transient 429 Too Many Requests (rate limiting) or 5xx errors can occur under high load. For
429, honor a Retry-After header when present and cap retries. Use exponential backoff with jitter
for retries.

Balance refresh errors

A forced refresh can return a 422 response when the live balance cannot be retrieved:

Withdraw funds

To withdraw funds from a customer's fiat account to their external bank account,
create a quote with side set to withdrawal:

{
  "product_type": "funding",
  "customer_guid": "customer_guid",
  "asset": "USD",
  "side": "withdrawal",
  "deliver_amount": 10000
}

Then create a funding transfer via POST /api/transfers:

{
  "quote_guid": "quote_guid",
  "transfer_type": "funding",
  "external_bank_account_guid": "external_bank_account_guid",
  "payment_rail": "wire",
  "beneficiary_memo": "Invoice #12345 payment",
  "source_participants": [
    {
      "type": "customer",
      "guid": "customer_guid",
      "amount": 10000
    }
  ],
  "destination_participants": [
    {
      "type": "customer",
      "guid": "customer_guid",
      "amount": 10000
    }
  ]
}

The external_bank_account_guid can reference any type of external bank account — Plaid-connected or raw routing.

Beneficiary memo

The optional beneficiary_memo parameter sets the memo that appears on bank statements
and wire confirmations for the beneficiary.

Constraints:

• Maximum 128 characters
• Cannot be an empty string — use null or omit the field to skip
• Only applies to withdrawal-direction funding transfers (not deposits, and not
  other transfer types such as book, crypto, or lightning)