Verified Modal

Who this is for: ISV partners embedding ProphetX in their own app or website.
This guide shows you how to drop the Verified Modal into your product so your
users can confirm their identity without ever leaving your experience.

Everything below uses the public ProphetX SDK — you don't need access to any internal
ProphetX systems or verification API keys to integrate.

What is the Verified Modal?

The Verified Modal is a small, ProphetX-hosted screen that pops up over your app to
walk a user through identity verification (KYC). It handles everything for you:

1. Asks for the user's phone number
2. Sends a one-time code by SMS and verifies it
3. Collects any extra details if needed (e.g. date of birth)
4. Shows a confirmation screen, then closes

When the user finishes, you get a simple callback telling you whether they passed,
failed, or were sent to manual review. That's it — you never touch the user's
personal data, and you never handle any verification API keys.

Where does the verification actually happen? The identity check itself is powered
by an external verification provider (the "Verified" service) — it's not a ProphetX
capability. But as an ISV you never deal with that provider directly. All the
client/server interaction happens on the embed side: the modal talks to the ProphetX
embed's own backend, which in turn talks to the verification provider for you. The
provider account, the API keys, the endpoints — all of that is already wired up inside
the embed. You need zero additional setup for the modal.

┌─────────────────────────────┐
│        Your App / Site       │
│                              │
│   [ Verify my identity ]  ◄──┼── you call open()
│                              │
│   ┌──────────────────────┐   │
│   │  ProphetX Verified   │   │ ◄── modal UI, served by the
│   │  ─────────────────   │   │     ProphetX embed (iframe overlay)
│   │   📱 Enter phone     │   │
│   │   🔑 Enter code      │   │        │
│   │   ✅ Confirm details │   │        │ all calls go to the
│   └──────────────────────┘   │        ▼ embed's own backend
│                              │   ┌──────────────────┐
│   onKycSuccess(identityUuid) │   │ ProphetX embed   │
└──────────────▲───────────────┘   │ backend (API)    │
               │                   └────────┬─────────┘
               │ callback                   │ proxies, holds the API key
               └───────────────────         ▼
                                   ┌──────────────────┐
                                   │ External Verified │
                                   │ service (provider)│
                                   └──────────────────┘

Everything to the left of the provider box is handled for you. As an ISV you only
ever interact with the box at the top: open the modal, receive a callback.

Two flavors: new user vs. existing user

There are two entry points. They look and behave the same to the user — the only
difference is who you're verifying.

Both take the exact same options and fire the exact same callbacks, so you can learn
one and you've learned both.

Quick start

React (@prophetx/sdk-react)

Wrap your app once in the provider, then open the modal from any component with a hook.

import { ProphetXProvider, useKyc } from '@prophetx/sdk-react';

// 1. Wrap your app once
function App() {
  return (
    <ProphetXProvider environment="production" token={yourSessionJwt}>
      <VerifyButton />
    </ProphetXProvider>
  );
}

// 2. Open the modal from anywhere inside the provider
function VerifyButton() {
  const { open } = useKyc(); // or useOnboarding() for new users

  return (
    <button
      onClick={() =>
        open({
          onKycSuccess: (identityUuid) => {
            // 🎉 User is verified — unlock prediction orders
            markUserVerified(identityUuid);
          },
          onKycFailed: (reason) => {
            // 🚫 Verification failed — keep orders blocked
            showVerificationBlockedMessage();
          },
          onKycPending: () => {
            // ⏳ Sent to manual review — check back later
            showPendingReviewMessage();
          },
          onCancel: () => {
            // User closed the modal without finishing
          },
        })
      }
    >
      Verify my identity
    </button>
  );
}

The hook also gives you close() and an isOpen boolean if you want to drive the
modal from your own state.

Vanilla JavaScript (@prophetx/sdk-js)

import { createProphetX } from '@prophetx/sdk-js';

const px = createProphetX({ environment: 'production' });

px.openKyc({
  // or px.openOnboarding({ ... }) for new users
  token: yourSessionJwt,
  onKycSuccess: (identityUuid) => markUserVerified(identityUuid),
  onKycFailed: (reason) => showVerificationBlockedMessage(),
  onKycPending: () => showPendingReviewMessage(),
  onCancel: () => {},
});

React Native (@prophetx/sdk-react-native)

The native SDK mirrors the same surface — wrap your screen in ProphetXProvider and
call useKyc() / useOnboarding() exactly as in React.

The callbacks (your only integration surface)

You don't deal with iframes, postMessage, or any of the verification API directly.
You just provide a few optional callbacks:

Your responsibility: ProphetX reports the outcome, but you decide what the
user can do. On onKycFailed (or anything other than a success), keep the user
blocked from placing prediction orders.

Environments

Set environment on the provider (React/RN) or createProphetX (JS):

Testing tips

• Sandbox returns mock data. In staging/sandbox, the flow returns a fixed
  test identity regardless of the phone number you enter, and pre-fills the date of
  birth with the sandbox test value — so you can click straight through.
• SMS is real in sandbox. The one-time code is delivered by real SMS, so use your
  own phone number when testing the code-entry step.

Frequently asked

Do I ever see the user's personal data (name, DOB, SSN)?
No. All personal data stays inside the ProphetX-hosted modal. You only ever receive an
opaque identityUuid on success.

Is the modal a ProphetX-built identity verifier?
No — the actual identity check is done by an external provider (the "Verified"
service). ProphetX builds and serves the modal UI and the backend that talks to that
provider, so from your side it all looks like one seamless ProphetX flow.

Do I need a verification provider account or API key?
No. The provider's API key lives server-side inside the ProphetX embed's backend,
which makes the provider calls on your behalf. You only need your ProphetX session
token — no account, keys, or endpoints to set up with the verification provider.

What if the user closes the modal halfway?
You get onCancel(). Nothing is verified; they can reopen and start again.

Can I style the modal to match my brand?
You can pass theme overrides to ProphetXProvider.