Skip to navigation
Embedded Onboarding

Embedded Onboarding Overview

Onboard your sub-merchants inside your own platform, with Coinflow’s onboarding and information requests embedded in an iframe.

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

1

Create and pre-fill a sub-merchant

Your backend calls Create Submerchant with your API key. Any business details you send are shown pre-filled to the sub-merchant.

2

Mint an embed session

When the sub-merchant opens onboarding in your product, your backend calls Create Embed Session and gets a short-lived token for that one sub-merchant.

3

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.

4

Follow progress

The iframe posts embed events to your page, Coinflow sends onboarding webhooks to your server, and Get Onboarding returns the current status at any time.

5

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.

The Integration Guide walks through each step with code. Before you start, complete 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 types can be added within the same version.

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