Onboarding Element

The Onboarding element embeds the frameOS KYC and compliance flow directly in your application as a modal. Unlike hosted onboarding sessions, no redirect is required — the flow opens inline and your users never leave your page.

Before opening the component, your server must create an account and request the capabilities you want to collect.

FULL EXAMPLE
<script src="https://js.framepayments.com/v1/index.js"></script>
<script>
  (async () => {
    const onboarding = await Frame.createOnboarding("<PUBLISHABLE_KEY>");
    onboarding.setAttribute("merchant-name", "My Company");

    onboarding.onSuccess = (account) => {
      console.log("Onboarding complete", account.id);
    };
    onboarding.onClose = () => {
      console.log("Modal closed");
    };

    // Open after your server creates the account and requests capabilities
    onboarding.open("<ACCOUNT_ID>");
  })();
</script>

Before you begin

The onboarding component requires an account to exist with capabilities already requested before you call open(). This must happen server-side using your secret key.

1. Create an account

REQUEST
curl --request POST \
  --url https://api.framepayments.com/v1/accounts \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "profile": {
    "individual": {
      "email": "user@example.com"
    }
  }
}'

2. Request capabilities

Capabilities determine which steps appear in the onboarding flow. Request only what your integration needs.

REQUEST
curl --request POST \
  --url https://api.framepayments.com/v1/accounts/<ACCOUNT_ID>/capabilities \
  --header 'Authorization: Bearer YOUR_SECRET_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "capabilities": ["kyc", "phone_verification", "card_receive"]
}'

See Capabilities for the full list of available capabilities.

3. Pass the account ID to your frontend and call onboarding.open(accountId).

API Reference

Frame.createOnboarding(publishableKey)

A lightweight factory that creates the onboarding web component. Unlike Frame.init(), this does not load Evervault, FingerprintJS, or Sift — it only loads what's needed for the onboarding flow.

Parameters
publishableKeyStringrequired

Your publishable API key from the Frame Dashboard.

Returns

Returns a FrameOnboarding element instance.

CREATE ONBOARDING ELEMENT
const onboarding = await Frame.createOnboarding("<PUBLISHABLE_KEY>");

Attributes

Set attributes on the element to customize the modal appearance.

Attributes
merchant-nameStringoptional

Display name shown inside the onboarding modal.

merchant-logoStringoptional

URL of the merchant logo shown in the modal header.

SET ATTRIBUTES
onboarding.setAttribute("merchant-name", "My Company");
onboarding.setAttribute("merchant-logo", "https://example.com/logo.png");

onboarding.open(accountId)

Loads the onboarding steps for the account and opens the modal. The account must already exist and have capabilities requested before calling open().

OPEN ONBOARDING
onboarding.open("acct_...");

onboarding.close()

Programmatically closes the modal.

CLOSE ONBOARDING
onboarding.close();

Callbacks

Assign callbacks directly on the element to respond to onboarding events.

Callbacks
onSuccess(account) => voidoptional

Called when all onboarding steps have been completed successfully. Receives the completed account object.

onError({ step, error }) => voidoptional

Called when a step encounters an error.

onStepComplete(step) => voidoptional

Called each time an individual step is completed.

onClose() => voidoptional

Called when the user closes the modal.

CALLBACKS
onboarding.onSuccess = (account) => {
  console.log("All steps complete", account.id);
};

onboarding.onError = ({ step, error }) => {
  console.error("Error on step", step, error.message);
};

onboarding.onStepComplete = (step) => {
  console.log("Step complete:", step);
};

onboarding.onClose = () => {
  console.log("Modal closed");
};