Skip to navigation
Embedded Onboarding

Partner Setup

Configure your Coinflow account before you embed onboarding: API keys, approved sites and webhooks.

Complete these steps once, in sandbox first and then in production, before you build the integration.

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

Webhook URLs are configured in the dashboard only. See Configuring Webhooks for the full walkthrough and 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.