> 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 Onboarding Overview

Embedded onboarding lets a platform that signs up businesses (an ISV) onboard
those businesses with Coinflow without sending them to Coinflow's dashboard.
Each business becomes a **sub-merchant** of your Coinflow account. You create
the sub-merchant and pre-fill what you already know about it, then show
Coinflow's onboarding inside your own product in an iframe. The sub-merchant
finishes its application, verifies its identity and answers any follow-up
questions from Coinflow's underwriting team without leaving your platform.

## When to use it

Use embedded onboarding when:

* your platform signs up businesses that need to accept payments or send payouts through Coinflow
* you want those businesses to apply from inside your product, not from a separate Coinflow login
* you want to track each business's onboarding progress from your own backend

## How it works

#### Create and pre-fill a sub-merchant

Your backend calls [Create Submerchant](/api-reference/api-reference/sub-merchant/create-submerchant) with your API key. Any business details you send are shown pre-filled to the sub-merchant.

#### Mint an embed session

When the sub-merchant opens onboarding in your product, your backend calls [Create Embed Session](/api-reference/api-reference/embed/create-embed-session) and gets a short-lived token for that one sub-merchant.

#### Embed the onboarding iframe

Your page loads Coinflow's onboarding in an iframe, passing the token in the URL fragment. The iframe keeps its own session alive.

#### Follow progress

The iframe posts [embed events](/guides/embedded-onboarding/embed-events) to your page, Coinflow sends [onboarding webhooks](/guides/embedded-onboarding/onboarding-webhooks) to your server, and [Get Onboarding](/api-reference/api-reference/onboarding/get-onboarding) returns the current status at any time.

#### Handle information requests

If underwriting needs more information, Coinflow sends a request for information (RFI). You open it for the sub-merchant in the same kind of iframe. See [Information Requests](/guides/embedded-onboarding/information-requests).

The [Integration Guide](/guides/embedded-onboarding/integration-guide) walks
through each step with code. Before you start, complete
[Partner Setup](/guides/embedded-onboarding/partner-setup).

## Security rules

Follow these rules in every integration:

* **Keep your API key on your server.** Create sub-merchants and mint embed sessions only from your backend. Never send your API key to a browser or mobile app.
* **Decide the sub-merchant on your server.** Your token endpoint must look up which sub-merchant the signed-in user belongs to from your own session. Never take the sub-merchant ID from a request parameter the browser controls, or any user could open another business's onboarding.
* **Treat embed session tokens as secrets.** Pass a token only in the URL fragment (`#token=...`), never in a query string, where it would reach server logs and `Referer` headers. Never log tokens or store them.
* **Check the message origin.** When you listen for embed events, ignore every message that doesn't come from the Coinflow origin and from your own iframe.

## Handling future changes

Coinflow adds to embedded onboarding over time without a new version. Build
your integration so that additions don't break it:

* **Ignore unknown fields** in API responses, webhook payloads and embed event payloads.
* **Handle unknown enum values.** New onboarding statuses, step statuses, RFI statuses and error codes may appear. Treat a status you don't recognize as still in progress.
* **Handle unknown step keys.** New onboarding steps may be added. Show or ignore them generically instead of failing.
* **Ignore unknown embed event types.** New event `type`s can be added within the same `version`.

Existing field names, enum values and step keys are never renamed or removed.