Skip to navigation
Embedded Accounts

Embedded Accounts Overview

Managed accounts under your primary Coinflow account, split payment settlement across them, and pay each one out independently.

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.

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

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.

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.

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.

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.

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

1

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.

2

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.

3

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.
  • Transfers - Move funds from your primary account into an embedded account from the Embedded Accounts page using New transfer.
4

Verify the account

Before an embedded account can be paid out, it must be verified. See 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.

5

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.

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"}'

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.

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:

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"
  }'
FieldDescription
nameThe account name. At least 2 characters, letters, numbers, and spaces only, and unique across your embedded accounts.
emailA contact email for the account.
managedTypebusiness or individual. Determines whether the account goes through business (KYB) or individual (KYC) verification.
groupThe 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.

The values above (the name, email, and GROUP_ID) are examples only.

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.

ControlDescription
Internal transfersAllows transfers between your primary account and embedded accounts. When disabled, the New transfer action is hidden.
Transfers between embedded accountsAllows 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 balanceA balance every account must keep. Transfers and withdrawals that would take an account below this amount are rejected.
Maximum primary account shareThe 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:

StatusMeaning
pendingThe transfer has been created and is waiting to be processed.
processingThe transfer is in progress.
completeThe funds have arrived at the destination.
canceledThe transfer was canceled before completing.
failedThe 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.