> 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.

# Partner Setup

Complete these steps once, in sandbox first and then in production, before you
build the [integration](/guides/embedded-onboarding/integration-guide).

> **Info**
>
> Your Coinflow account must be enabled for sub-merchants before you can create
> them. Contact your Coinflow integrations representative to turn this on and to
> confirm which payment and payout products your sub-merchants can apply for.

## 1. Create an API key

In the merchant dashboard, go to **Developers → API Keys** and create a key.

* Use an **Admin** key to create sub-merchants and mint embed sessions.
* [Get Onboarding](/api-reference/api-reference/onboarding/get-onboarding) and [List RFIs](/api-reference/api-reference/rfi/list-rfis) work with any key of Viewer scope or higher.

Store the key on your server only. An embed session stops working as soon as
the API key that minted it is disabled, deleted or downgraded below Admin.

## 2. Approve the sites that embed onboarding

Coinflow only lets onboarding load inside pages on sites you've approved. Add
every origin that will frame the iframe, such as `https://app.example.com`,
under **Whitelist URLs** in the merchant dashboard. Follow
[Whitelist URLs](/guides/checkout/payment-security-risk-management/checkout-security/whitelist-ur-ls)
to submit a request; the Coinflow team reviews each one.

* Wildcards such as `https://*.example.com` are supported. They cover subdomains only, so add `https://example.com` separately if you embed on the bare domain.
* Add the site to your own account. Your sub-merchants inherit it, so you don't need to add it to each sub-merchant.
* If you send sub-merchants back to your platform after they submit (`returnUrl`), that URL's origin must be approved too.
* Approve your sandbox and local development origins in sandbox, and only your production origins in production.

Minting an embed session with a `parentOrigin` fails with a `400` until the
origin is covered by an approved URL.

## 3. Set up webhooks

Onboarding webhooks tell your server when a sub-merchant submits, is approved
or declined, or gets an information request.

1. In the merchant dashboard, go to **Developers → Webhooks**.
2. Add the URL of the endpoint on your server and generate a **Webhook Validation Key**.
3. Choose webhook **Version 2** or later and subscribe to the five sub-merchant onboarding events listed in [Onboarding Webhooks](/guides/embedded-onboarding/onboarding-webhooks).

Webhook URLs are configured in the dashboard only. See
[Configuring Webhooks](/guides/developer-resources/webhooks/configuring-webhooks)
for the full walkthrough and
[Verifying Webhook Signatures](/guides/developer-resources/webhooks/verifying-webhook-signatures)
to validate deliveries.

## 4. Settlement options (optional)

If your sub-merchants should choose where their funds settle during onboarding,
ask your Coinflow integrations representative to enable the settlement options
you want to offer. Onboarding only shows the settlement step when at least one
option is enabled.

## Who to contact

Your Coinflow integrations representative enables sub-merchants on your
account, reviews Whitelist URL requests and enables settlement options. For
developer questions, see [Developer Contact](/guides/merchant-dashboard/developer-contact).