Embedded Onboarding Integration Guide

Create and pre-fill a sub-merchant

Call Create Submerchant from your backend when a business signs up for payments on your platform.

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/submerchant \
  --header "Authorization: $COINFLOW_ADMIN_API_KEY" \
  --header 'content-type: application/json' \
  --data '{
    "merchantId": "acme-store",
    "email": "owner@acme.example.com",
    "dba": "Acme Store",
    "industry": "retailEcommerce",
    "businessEmail": "support@acme.example.com",
    "billingEmailSameAsBusinessEmail": true,
    "websiteUrls": ["https://acme.example.com"],
    "privacyPolicyUrl": "https://acme.example.com/privacy",
    "termsOfServiceUrl": "https://acme.example.com/terms",
    "payinMethods": "card,applePay"
  }'

{
  "merchantId": "acme-store",
  "email": "owner@acme.example.com",
  "dba": "Acme Store",
  "industry": "retailEcommerce",
  "businessEmail": "support@acme.example.com",
  "billingEmail": "support@acme.example.com",
  "websiteUrl": "https://acme.example.com",
  "privacyPolicyUrl": "https://acme.example.com/privacy",
  "termsOfServiceUrl": "https://acme.example.com/terms",
  "payinMethods": "card,applePay",
  "products": "checkout"
}

• merchantId is your identifier for the sub-merchant: 3 to 50 letters, numbers and hyphens, unique across Coinflow. It’s stored in lowercase, so on every later call for this sub-merchant, send the merchantId returned in the response as the x-coinflow-submerchant-id header. Later lookups match the exact case.
• email becomes the sub-merchant’s account owner. Use a real inbox the business can open: Coinflow emails the account owner, for example a one-time code during settlement setup.
• Every other field is optional. Anything you send is shown to the sub-merchant pre-filled, and they can change it. Some fields don’t apply to every sub-merchant; those are accepted and kept but not shown.
• Don’t send the x-coinflow-submerchant-id header on this call. It fails with a 400.

Pre-fill fields

Unknown fields are rejected with a 400. The response returns the URLs as separate fields (websiteUrl, websiteUrl2, …) and adds products, derived from the pay-in and payout methods you sent.

Updating pre-filled details

Call Update Submerchant with only the fields you want to change:

curl --request PATCH \
  --url https://api-sandbox.coinflow.cash/api/submerchant/acme-store \
  --header "Authorization: $COINFLOW_ADMIN_API_KEY" \
  --header 'content-type: application/json' \
  --data '{"businessPhoneNumber": "4155550142", "businessPhoneCountryCode": "+1"}'

• Fields you leave out keep their current values. websiteUrls and developmentUrls replace the whole list.
• Once the sub-merchant submits its application, updates fail with a 409.

Mint an embed session from your backend

When a signed-in user opens onboarding in your product, your backend mints an embed session for their sub-merchant with Create Embed Session and returns the token to your page.

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/embed/session \
  --header "Authorization: $COINFLOW_ADMIN_API_KEY" \
  --header 'x-coinflow-submerchant-id: acme-store' \
  --header 'content-type: application/json' \
  --data '{"parentOrigin": "https://app.example.com"}'

{
  "token": "EMBED_SESSION_TOKEN",
  "expiresAt": 1767225600
}

• parentOrigin is the origin of the page that frames the iframe. It must be covered by an approved Whitelist URL. The iframe only posts events to this origin.
• expiresAt is in Unix seconds.

A minimal token endpoint in Node.js with Express:

app.post('/coinflow/onboarding-session', requireSignedInUser, async (req, res) => {
  // Look up the sub-merchant from your own session, never from the request.
  const submerchantId = await getSubmerchantIdForUser(req.user.id);
  const response = await fetch(
    'https://api-sandbox.coinflow.cash/api/embed/session',
    {
      method: 'POST',
      headers: {
        Authorization: process.env.COINFLOW_ADMIN_API_KEY,
        'x-coinflow-submerchant-id': submerchantId,
        'content-type': 'application/json',
      },
      body: JSON.stringify({parentOrigin: 'https://app.example.com'}),
    }
  );
  if (!response.ok) return res.sendStatus(502);
  const {token} = await response.json();
  res.set('Cache-Control', 'no-store').json({token});
});

Session lifetime and renewal

• Each token is valid for 15 minutes. The iframe renews its own token about 2 minutes before it expires, so you mint once per visit.
• A session can’t be renewed past 8 hours after it was minted. After that the iframe posts an onboarding.error event with code session_expired; mint a new token and reload the iframe.
• A session stops working immediately if the sub-merchant is moved out of your account, either account is suspended, or the API key that minted it is disabled, deleted or downgraded below Admin.

If you call embed-session APIs directly, renew a token with Refresh Embed Session.

Embed the onboarding iframe

Load the onboarding page with the token in the URL fragment:

<iframe
  id="coinflow-onboarding"
  src="https://sandbox-merchant.coinflow.cash/embed/onboarding#token=EMBED_SESSION_TOKEN"
  title="Coinflow onboarding"
  allow="camera; microphone; clipboard-write"
  style="width: 100%; border: 0;"
></iframe>

• The allow attribute is required. Identity verification runs in a frame inside the iframe and uses the camera to capture ID documents and a selfie. A nested frame only gets the permissions every frame above it grants, so without camera the sub-merchant can’t verify. Include microphone as well, since verification may request it. clipboard-write powers the Copy link buttons used to share verification links with business owners.
• Use the fragment, not a query string. The fragment is never sent to a server or leaked in Referer headers, and the iframe removes it from its address bar as soon as it loads.
• Size it for one column. Onboarding shows one step at a time and works down to about 320px wide. Set the iframe’s height from onboarding.heightChanged events (next step) so it never shows its own scrollbar.
• Don’t sandbox it unless the sandbox attribute includes allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox. Documents and terms open in a new tab, and without allow-popups-to-escape-sandbox that tab inherits the sandbox and can’t display them.

The iframe only renders on approved sites. On any other site, or when the token is missing or invalid, it shows a “Not allowed” message instead.

Follow progress

You have three ways to follow a sub-merchant’s progress. Most integrations use all three.

Listen for embed events from your page:

const COINFLOW_ORIGIN = 'https://sandbox-merchant.coinflow.cash';
const iframe = document.getElementById('coinflow-onboarding') as HTMLIFrameElement;
window.addEventListener('message', event => {
  if (event.origin !== COINFLOW_ORIGIN) return;
  if (event.source !== iframe.contentWindow) return;
  const message = event.data;
  if (message?.source !== 'coinflow' || message.version !== 1) return;
  switch (message.type) {
    case 'onboarding.heightChanged':
      iframe.style.height = `${message.payload.height}px`;
      break;
    case 'onboarding.stepChanged':
      iframe.scrollIntoView({block: 'start'});
      break;
    case 'onboarding.submitted':
      showSubmittedBanner();
      break;
    case 'onboarding.error':
      if (message.payload.code === 'session_expired') reloadWithNewSession();
      break;
  }
});

Read the current status from your backend:

curl --request GET \
  --url https://api-sandbox.coinflow.cash/api/onboarding \
  --header "Authorization: $COINFLOW_API_KEY" \
  --header 'x-coinflow-submerchant-id: acme-store'

{
  "merchantId": "acme-store",
  "status": "in_progress",
  "requirementsStatus": "determined",
  "requirementsRevision": 2,
  "openRfiCount": 0,
  "steps": [
    {"key": "profile", "status": "complete", "dependsOn": [], "blockedBy": [], "completionMethods": ["embed"]},
    {"key": "corporate_structure", "status": "complete", "dependsOn": ["profile"], "blockedBy": [], "completionMethods": ["embed"]},
    {"key": "verification", "status": "action_required", "dependsOn": ["profile", "corporate_structure"], "blockedBy": [], "completionMethods": ["embed"]},
    {"key": "application", "status": "blocked", "dependsOn": ["profile", "corporate_structure", "verification"], "blockedBy": ["verification"], "completionMethods": ["embed"]}
  ]
}

Onboarding statuses

Steps

steps lists only the steps that apply to this sub-merchant, in order. Each step has a status of blocked (waiting on the steps in blockedBy), action_required, in_review or complete.

While requirementsStatus is pending, more steps may be added once the sub-merchant completes its profile. requirementsRevision increases each time the list of steps is recalculated.

Handle information requests

After the sub-merchant applies, or at any time after it’s live, Coinflow’s underwriting team may send it a request for information (RFI). Coinflow doesn’t email the sub-merchant about these, so your platform must show them.

1. Listen for the Sub-merchant RFI Sent webhook, or call List RFIs with actionRequired=true.
2. Mint an embed session for the sub-merchant, exactly as in step 2.
3. Open the RFI in an iframe at /embed/rfi/{rfiId}#token=EMBED_SESSION_TOKEN.

See Information Requests for the details.