> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# Embedded Accounts Overview

## Overview

Embedded accounts allow you to configure subsidiaries under your Coinflow merchant account. Every merchant has a **primary account**, which holds all settled funds by default. When embedded accounts are enabled, you can create additional **embedded accounts** alongside it. Each embedded account has its own balance, its own transfer history, and its own payout methods.

Use embedded accounts when you need to keep money for different purposes, business units, or partners apart without opening a separate Coinflow merchant account for each one.

> **Info**
>
> Embedded accounts are not enabled by default. Contact the Coinflow integrations team to enable them on your merchant account.

## When to use embedded accounts

* **Segregating funds** - Keep revenue for different brands, programs, or business lines with their own balances.
* **Splitting settlement** - Route a portion of every payment directly into one or more embedded accounts at checkout, instead of moving money after the fact.
* **Independent payouts** - Pay out each embedded account to its own bank account, wire, or card without touching the funds in your primary account.
* **Reserves and operating funds** - Hold a reserve in one account while keeping operating funds in another, and move money between them as needed.

## Key concepts

#### Primary account

The account that holds all settled funds by default. It always exists, cannot be removed, and is the counterparty for transfers to and from embedded accounts.

#### Group

A named collection of embedded accounts, such as a brand, region, or partner program. Every embedded account belongs to a group, so you create at least one group before creating accounts. Groups organize the Embedded Accounts page and let you list accounts for one part of your business at a time.

#### Embedded account

A separate balance under your merchant account. Each embedded account has a name, a contact email, an account type (individual or business), a group, a status, a balance, and a verification state. Embedded accounts must be verified before they can be paid out.

#### Transfer

A movement of funds between your primary account and an embedded account. Depending on your configuration, transfers may also be allowed directly between two embedded accounts.

#### Withdrawal

A payout from an embedded account's balance to one of that account's payout methods, such as a bank account, wire, or debit card.

## How it works

#### Create a group

In the Merchant Dashboard, open **Embedded Accounts** under **General** in the sidebar and select **Add group**. Provide a name (at least 2 characters, letters, numbers, and spaces only). Group names must be unique, ignoring case. See [Groups](#groups).

#### Create an embedded account

Select **Add account**, or the add action on a group, and provide:

* **Name** - At least 2 characters, letters, numbers, and spaces only. Names must be unique across your embedded accounts.
* **Email** - A contact email for the account.
* **Group** - The group the account belongs to.
* **Account type** - **Business** or **Individual**. This determines which verification the account goes through.

New accounts start in a `pending` status and become `active` once they are ready to hold funds. You can also create accounts with the API. See [Creating accounts with the API](#creating-accounts-with-the-api).

#### Fund the account

Embedded accounts can be funded in two ways:

* **Split settlement at checkout** - When generating a destination auth key, provide a list of destinations with either fixed amounts or percentages. See [Settlement](/guides/embedded-accounts/settlement).
* **Transfers** - Move funds from your primary account into an embedded account from the Embedded Accounts page using **New transfer**.

#### Verify the account

Before an embedded account can be paid out, it must be verified. See [Verification](/guides/embedded-accounts/verification). The `verified` field on each account returned by the API shows its current state, and the **Withdrawal** dialog tells you when an account still needs to be verified.

#### Pay out

Select **Withdrawal** on a verified embedded account, choose one of its payout methods and a payout speed, and enter an amount. The withdrawal is drawn from that account's balance only.

## Groups

Groups keep a large number of embedded accounts manageable. On the Embedded Accounts page, each group is a collapsible section that loads its accounts, with their balances, when you expand it. Only one group is open at a time, so opening a group closes the one that was open.

To find an account without browsing groups, type part of its name in the search box above the groups. Selecting a result opens that account's group and highlights the account.

Use groups to mirror how your business is organized, for example one group per brand, per region, or per partner program.

### Managing groups with the API

All requests below use your API key in the `Authorization` header.

#### Create a group

```bash
curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/merchant/accounts/embedded-groups \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"name": "West Region"}'
```

```json
{"id": "GROUP_ID", "name": "West Region"}
```

#### List groups

```bash
curl --request GET \
  --url https://api-sandbox.coinflow.cash/api/merchant/accounts/embedded-groups \
  --header 'Authorization: YOUR_API_KEY'
```

```json
[{"id": "GROUP_ID", "name": "West Region"}]
```

Groups are returned sorted by name.

#### List a group's accounts

```bash
curl --request GET \
  --url https://api-sandbox.coinflow.cash/api/merchant/accounts/embedded-groups/GROUP_ID/accounts \
  --header 'Authorization: YOUR_API_KEY'
```

```json
[
  {
    "name": "Store 12",
    "accountId": "EMBEDDED_ACCOUNT_ID",
    "address": "EMBEDDED_ACCOUNT_ADDRESS",
    "status": "active",
    "balance": {"cents": 125000, "currency": "USD"},
    "transferPending": false,
    "verified": true
  }
]
```

#### Search accounts by name

```bash
curl --request GET \
  --url 'https://api-sandbox.coinflow.cash/api/merchant/accounts/embedded-accounts/search?name=store' \
  --header 'Authorization: YOUR_API_KEY'
```

```json
[
  {
    "name": "Store 12",
    "group": "West Region",
    "groupId": "GROUP_ID",
    "accountId": "EMBEDDED_ACCOUNT_ID"
  }
]
```

Search matches part of the account name, ignoring case, across all your groups and returns up to 10 results sorted by name. Each result includes the name and ID of the account's group. Use search to find an account's ID without loading every group, then pass `groupId` to **List a group's accounts** to get its balance and status.

> **Warning**
>
> The values above (`GROUP_ID`, `EMBEDDED_ACCOUNT_ID`, `EMBEDDED_ACCOUNT_ADDRESS`, the names, and the balance) are **examples only**. Use the IDs returned by your own requests.

## Creating accounts with the API

To create an embedded account, send its name, contact email, account type, and the ID of its group:

```bash
curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/merchant/accounts/embedded-accounts \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Store 12",
    "email": "store12@example.com",
    "managedType": "business",
    "group": "GROUP_ID"
  }'
```

| Field         | Description                                                                                                              |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `name`        | The account name. At least 2 characters, letters, numbers, and spaces only, and unique across your embedded accounts.    |
| `email`       | A contact email for the account.                                                                                         |
| `managedType` | `business` or `individual`. Determines whether the account goes through business (KYB) or individual (KYC) verification. |
| `group`       | The ID of the group to add the account to. The group must belong to your merchant account.                               |

The response is the withdrawer record created for the account. Its `wallet` is the embedded account ID, which you use to verify the account and to add payout methods. See [Verification](/guides/embedded-accounts/verification).

> **Warning**
>
> The values above (the name, email, and `GROUP_ID`) are **examples only**.

> **Tip**
>
> If you create an account with the same name as one you removed, the removed account is restored with a zero balance. It must be verified again and its payout methods added again. The account type must match the type it had before.

## Account controls

Your embedded accounts configuration can include the following controls. These are set by Coinflow - contact the integrations team to enable or change them.

| Control                                 | Description                                                                                                                                                              |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Internal transfers**                  | Allows transfers between your primary account and embedded accounts. When disabled, the **New transfer** action is hidden.                                               |
| **Transfers between embedded accounts** | Allows funds to move directly from one embedded account to another. When disabled, every transfer must have the primary account as either its source or its destination. |
| **Minimum balance**                     | A balance every account must keep. Transfers and withdrawals that would take an account below this amount are rejected.                                                  |
| **Maximum primary account share**       | The highest percentage of a split payment that may settle to your primary account. Destination auth key requests that exceed it are rejected.                            |

## Transfer and withdrawal rules

* An account can only have **one pending transfer or withdrawal at a time**. Wait for it to complete before starting another from the same account.
* Transfers and withdrawals cannot exceed the source account's balance, or take it below the configured minimum balance.
* The transfer source and destination must be different accounts.
* Withdrawals require the embedded account to be **verified** and the selected payout method to support the chosen speed.
* If a withdrawal is returned (for example, by the receiving bank), the funds are credited back to the embedded account it came from.

Each account's transfer history is available from the Embedded Accounts page, with one of the following statuses:

| Status       | Meaning                                                       |
| ------------ | ------------------------------------------------------------- |
| `pending`    | The transfer has been created and is waiting to be processed. |
| `processing` | The transfer is in progress.                                  |
| `complete`   | The funds have arrived at the destination.                    |
| `canceled`   | The transfer was canceled before completing.                  |
| `failed`     | The transfer could not be completed.                          |

## Removing an embedded account

Embedded accounts with a zero balance can be removed from the Embedded Accounts page. Transfer and payout history for a removed account is retained. The primary account cannot be removed, and an account with a pending transfer or withdrawal cannot be removed until it completes.