Frontend Integration Guide

Embeddable deposit, withdraw, onboarding, and KYC flows for ISV partners.

Add ProphetX-hosted deposit, withdrawal, onboarding, and KYC flows to your frontend using the SDK for your stack.

📘

ProphetX provides embeddable deposit, withdraw, onboarding, and KYC flows for ISV partners. Each SDK works like a drop-in that you wrap around your app and call from a button.

🎥

See it live: isv-embed-fe-mock-isv-host.vercel.app is a demo ISV host app running all four flows end to end — a working reference before you write any code. It starts on Staging; switch to Sandbox in its Dev Settings.

There are four SDKs — pick the one that matches your stack:

StackPackageInstall
React (web)@prophetx/sdk-reactnpm i @prophetx/sdk-react
Vanilla JS@prophetx/sdk-jsnpm i @prophetx/sdk-js
React Native@prophetx/sdk-react-nativenpm i @prophetx/sdk-react-native react-native-webview @react-native-async-storage/async-storage
Flutterprophetx_sdk (Dart)Add to pubspec.yaml (see Flutter)

All four expose the same flows and events. The differences: React, React Native and Flutter configure token, theme and locale once on a provider, while Vanilla JS passes them on each open* call; appLink exists only on the native SDKs; and the rendering primitive differs (iframe vs. WebView).


Table of Contents

  1. What You Get
  2. Before You Start
  3. Quick Start (React)
  4. Quick Start (Vanilla JS)
  5. Quick Start (React Native)
  6. Quick Start (Flutter)
  7. Available Flows
  8. Built-In Modules
  9. Environments
  10. Lifecycle & Cleanup
  11. Error Codes
  12. API Reference Cheat Sheet
  13. FAQ & Troubleshooting

1. What You Get

Four end-user flows, fully implemented and hosted by ProphetX:

FlowWhat the user does
DepositPicks a payment method — Online Bank (AeroPay), Crypto (ZeroHash), Debit Card, Apple Pay, Google Pay, Cash at Retail (all PayNearMe), or Wire Transfer — enters an amount, and funds their ProphetX wallet.
WithdrawEnters an amount and withdraws by Online Bank (AeroPay), to a debit card they've deposited with (PayNearMe), or by Wire Transfer. Crypto withdrawals aren't available.

Each method, its limits and what your app has to set up for it are on Payment Methods.
| 1-Click Signup | New-user identity creation via Verified Inc's own hosted modal. |
| Document verification | Re-verification flow for existing users whose automated KYC came back FAILURE. |

Each flow opens in a modal on web, full screen on React Native, and in a bottom sheet (88% of the screen height) on Flutter. You get callbacks on success, error, cancel, and KYC outcomes, plus a global event stream for analytics.

Out of the box you also get:

  • Built-in authentication with token storage and auto-refresh
  • Wallet balance API
  • Theming — match the embed to your brand at open time or dynamically
  • Geofence handling — know when a user's location blocks a flow
  • DevTools — toggle-on debug logger with automatic PII redaction
  • Three environments — production, staging, sandbox

2. Before You Start

Before you integrate the SDK:

  1. Create a ProphetX partner account — talk to ProphetX onboarding to get your sandbox/staging credentials.
  2. Provide a session JWT for each user — your backend mints an embed token with GET /private/v1/tokens and passes it to your frontend — see Embedded UI. 1-Click Signup uses a session key from POST /private/v1/one-click/sessions instead — see Identity Verification.
  3. Allow-list your origins — coordinate with ProphetX before going live so your production domains can render the embed.
  4. Display "Powered by ProphetX" branding — this is a certification requirement, not optional. It must appear in four places: the T&Cs modal, the deposit modal, the withdrawal modal, and the trade placement/confirmation screens. This is checked during certification, so build it in from the start rather than discovering it as a blocker right before go-live.
📘

The SDK never asks you to embed payment provider SDKs (AeroPay, ZeroHash, PayNearMe) directly — those all live inside the ProphetX-hosted embed. Wire Transfer is shown to every user; the other methods appear only when they're enabled for the user's account.


3. Quick Start (React)

npm i @prophetx/sdk-react

Wrap your app once, then call hooks anywhere inside.

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

function App() {
  return (
    <ProphetXProvider
      environment="production"
      token={sessionJwt}                     // minted by your backend with GET /private/v1/tokens
    >
      <WalletButtons />
    </ProphetXProvider>
  );
}

function WalletButtons() {
  const deposit  = useDeposit();
  const withdraw = useWithdraw();

  return (
    <>
      <button onClick={() => deposit.open({
        onSuccess: (txId, amount) => console.log('Deposited', txId, amount),
        onError:   (code, msg)    => console.error('Deposit failed', code, msg),
        onCancel:  () => console.log('User cancelled'),
      })}>
        Deposit
      </button>

      <button onClick={() => withdraw.open({
        onSuccess: (txId, amount) => console.log('Withdrew', txId, amount),
        onError:   (code, msg)    => console.error('Withdrawal failed', code, msg),
      })}>
        Withdraw
      </button>
    </>
  );
}

You now have a basic deposit and withdrawal button wired to ProphetX-hosted flows.


4. Quick Start (Vanilla JS)

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

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

document.querySelector('#deposit-btn').addEventListener('click', () => {
  px.openDeposit({
    token: sessionJwt,
    onSuccess: (txId, amount) => console.log('Deposited', txId, amount),
    onError:   (code, msg)    => console.error(code, msg),
    onCancel:  () => console.log('User cancelled'),
  });
});

// Clean up when your page tears down
window.addEventListener('beforeunload', () => px.destroy());

Every open* call needs a token unless you configured the auth module; without either, it throws No token provided.

createProphetX returns an SDKInstance with openDeposit / openWithdraw / openOnboarding (gated — see warning below) / openOneClickSignup / openKyc (or openIdUpload) / close / destroy / updateTheme / updateLocale / on / off / auth / wallet.


5. Quick Start (React Native)

npm i @prophetx/sdk-react-native react-native-webview @react-native-async-storage/async-storage
cd ios && pod install      # iOS only

Peer dependencies: react ^18 || ^19, react-native >=0.70, react-native-webview >=13, @react-native-async-storage/async-storage >=1.19.

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

export default function App() {
  return (
    <ProphetXProvider environment="production" token={sessionJwt}>
      <Home />
    </ProphetXProvider>
  );
}

function Home() {
  const { open } = useDeposit();
  return <Button title="Deposit" onPress={() => open({
    onSuccess: (txId, amount) => console.log('Deposited', txId, amount),
    onError:   (code, msg)    => console.error('Deposit failed', code, msg),
  })} />;
}

The provider mounts a full-screen modal with header + WebView when you open a flow. You don't render the WebView yourself — but a low-level ProphetXWebView is exported if you need custom chrome.

📘

iOS/Android setup: make sure your app has Internet permission (Android) and that NSAppTransportSecurity is not blocking HTTPS (iOS).


6. Quick Start (Flutter)

Add to pubspec.yaml:

dependencies:
  prophetx_sdk: ^0.5.0

prophetx_sdk is published on pub.dev. It needs Dart 3.4 or later and Flutter 3.16 or later.

Mount ProphetXProvider inside MaterialApp, not above it. The SDK opens its modal in the app's Overlay, which MaterialApp provides; above it the modal chrome can't render.

import 'package:flutter/material.dart';
import 'package:prophetx_sdk/prophetx_sdk.dart';

void main() {
  runApp(
    MaterialApp(
      home: ProphetXProvider(
        environment: EnvironmentName.production,
        token: sessionJwt,
        child: const HomeScreen(),
      ),
    ),
  );
}

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final px = ProphetX.of(context);
    return ElevatedButton(
      onPressed: () => px.deposit.open(OpenDepositOptions(
        onSuccess: (id, amount) => debugPrint('deposit success $id'),
        onError: (code, message) => debugPrint('deposit failed $code: $message'),
      )),
      child: const Text('Deposit'),
    );
  }
}

Native deps the SDK pulls in: webview_flutter, url_launcher, flutter_secure_storage, http, flutter_svg, uuid. Android cleartext is not required for production/staging since the API base URLs are HTTPS.


7. Available Flows

Every flow follows the same pattern: call open() with the callbacks you need.

flow.open({
  // Every flow
  onReady?, onError?, onCancel?, onGeofenceBlocked?,

  // Deposit and withdraw
  onSuccess?, onSuccessAction?, initialAmount?, successButtonLabel?,
  appLink?,               // React Native and Flutter only

  // Document verification (useIdUpload / useKyc)
  onKycSuccess?, onKycFailed?, onKycPending?,
  redirectUrl?,           // useIdUpload only

  // 1-Click Signup (required: sessionKey, environment)
  onOneClickSuccess?, onOneClickFailed?, onOneClickDeclined?,
});

In React, React Native and Flutter, token, theme, locale and onSessionExpired belong on ProphetXProvider, not on open(). Only the Vanilla JS SDK takes them per call — see Options shared by all flows.

Deposit

User picks method → enters amount → confirms → completes via provider.

// React
const { open } = useDeposit();
open({
  onSuccess: (txId, amount) => track('deposit_success', { txId, amount }),
  onError:   (code, msg)    => track('deposit_error', { code, msg }),
  onCancel:  ()             => track('deposit_cancel'),
});

Possible error codes: DEPOSIT_FAILED (generic fallback), DEPOSIT_UNCONFIRMED, DEPOSIT_NOT_COMPLETED, DEPOSIT_WALLET_WRITE_FAILED, PROVIDER_LOAD_FAILED, PROVIDER_UNAVAILABLE, PAYNEARME_DEPOSIT_FAILED, GEOFENCE_BLOCKED, plus eight ZEROHASH_* codes. The deposit table says what the embed shows after each one and what to do. Location is checked twice: when the flow opens, which fires onGeofenceBlocked, and again just before the deposit is submitted, which fires onError('GEOFENCE_BLOCKED', message) — see Geofence.

Withdraw

const withdraw = useWithdraw();
const idUpload = useIdUpload();

withdraw.open({
  onSuccess: (txId, amount) => console.log('Withdrew', txId, amount),
  onError:   (code, msg) => {
    if (code === 'KYC_REQUIRED') {
      // This user already exists (they have an embed token) — re-verify them,
      // don't send them through signup.
      idUpload.open();
    }
  },
});

Possible error codes: WITHDRAWAL_FAILED (generic fallback), WITHDRAWAL_UNCONFIRMED, WITHDRAWAL_NOT_COMPLETED, WITHDRAWAL_WALLET_WRITE_FAILED, PAYNEARME_WITHDRAWAL_FAILED, PROVIDER_ERROR, ZEROHASH_PROVIDER_ERROR, GEOFENCE_BLOCKED, and KYC_REQUIRED. KYC_REQUIRED comes from the embed when an Online Bank withdrawal is refused because the user's identity isn't verified; its backend source is still unconfirmed. See the withdrawal table.

1-Click Signup (new-user identity)

triangle-exclamation

useOnboarding/openOnboarding — previously documented here — is not available: the route is permanently gated off with an error screen (the underlying Verified Inc API integration was never approved for that integration type). Use useOneClickSignup for new users instead.

Use this the first time a brand-new user signs up — there's no ProphetX user yet, so there's no embed token either. Verified Inc's own hosted modal handles phone/OTP lookup and PII confirmation; your backend mints a sessionKey first and redeems the resulting identity afterward. KYC hasn't run yet at that point — it starts once your backend redeems the identity, and can still come back FAILURE. See Identity Verification for the full contract (sessionKey/environment, onOneClickSuccess/onOneClickDeclined/onOneClickFailed).

const { open } = useOneClickSignup();
const { sessionKey, environment } = await myBackend.mintOneClickSession();
open({
  sessionKey,
  environment,
  onOneClickSuccess: (identityUuid) => myBackend.redeem(identityUuid),
  onOneClickDeclined: () => showManualSignupForm(),
  onOneClickFailed: (reason, retryable) => console.warn('1-Click failed', reason, retryable),
});

Document verification (existing-user re-verification)

For an existing user whose automated KYC came back FAILURE, use useKyc (historical alias) or useIdUpload (preferred) — a government-ID photo upload reviewed by IDComply, opened in a second browser tab. There's no phone/OTP step in this flow. See Identity Verification for the full walkthrough.

const idUpload = useIdUpload(); // or useKyc — same flow
idUpload.open({
  onKycSuccess: () => handleSuccess(),          // also fires if the user was already verified
  onKycFailed: (reason) => routeToSupport(reason), // always final; log reason, don't show it
  onKycPending: () => toast('Identity check pending review'),
});

8. Built-In Modules

Authentication

Use a token from your backend. Your backend mints an embed token for the user with GET /private/v1/tokens (see Embedded UI) and hands it to your frontend. Pass it as token, and add an onSessionExpired handler that returns a fresh one. See Session refresh below. Tokens last 10 minutes by default, so mint one right before you open a flow.

The auth module. The SDKs also ship an email/password auth module. It logs in by calling POST {apiBaseUrl}/api/v1/auth/login.

⚠️

isv-api doesn't serve /api/v1/auth/login, so the auth module can't log a user in against the ProphetX API today. Use a backend-minted token instead. The rest of this section describes the module as the SDKs expose it.

Pass an auth config; the SDK handles login, storage, and JWT decoding. To have it log in again on its own before the token expires, also pass getCredentials.

// React
<ProphetXProvider
  environment="staging"
  auth={{
    apiBaseUrl: 'https://isv-api.staging.prophetx.dev',
    // Needed for auto-refresh: called when the token is about to expire
    getCredentials: async () => ({ email: savedEmail, password: await readPassword() }),
    refreshBufferSeconds: 30,   // refresh 30s before expiry
  }}
>
  <App />
</ProphetXProvider>

// useAuth() throws unless ProphetXProvider has an `auth` prop
function Login() {
  const { login, logout, isAuthenticated, state } = useAuth();

  if (!isAuthenticated) {
    return (
      <button onClick={() => login({ email: '[email protected]', password: 'pw' })}>
        Sign in
      </button>
    );
  }
  const expiresAt = state.status === 'authenticated' ? state.expiresAt : undefined; // Unix seconds
  return <button onClick={logout}>Sign out (expires {expiresAt})</button>;
}
// Vanilla JS
const px = createProphetX({
  environment: 'staging',
  auth: { apiBaseUrl: 'https://isv-api.staging.prophetx.dev' },
});

await px.auth.login({ email, password });
px.auth.onStateChange((state) => console.log('Auth →', state.status));
px.auth.logout();

Auth states: unauthenticated → authenticating → authenticated. When the token nears expiry, the SDK calls getCredentials and logs in again; without getCredentials it moves to expired and stops there until you call login(). Login errors land in error: INVALID_CREDENTIALS for a 401, and SERVER_ERROR for anything else — including timeouts and lost connections. TIMEOUT exists in the error type, but login() doesn't report it today. See SDK client errors.

Device ID is auto-generated (crypto.randomUUID()) and persisted (localStorage on web, AsyncStorage on RN, flutter_secure_storage on Flutter). You can override with login({ email, password, deviceId }).

Wallet / Balance

On React and React Native, useWallet() fetches the user's balance from GET /embed/v1/wallet with the token you passed.

// React — needs `environment` on ProphetXProvider, or useWallet() throws.
// It doesn't fetch on its own: call refetch() when you want a balance.
const { balance, loading, error, refetch } = useWallet();
useEffect(() => { refetch(); }, [refetch]);
return loading ? <Spinner /> : <p>${balance?.totalBalance}</p>;
// Vanilla JS — px.wallet is null unless createProphetX got both `auth` and `environment`.
// Because the auth module can't log in today, fetch the balance from your own backend instead.
if (px.wallet) {
  const { totalBalance, currency } = await px.wallet.getBalance();
}

Refresh the balance after onCancel as well as onSuccess: Cash at Retail and Wire Transfer never send onSuccess, and onSuccess can arrive while a deposit is still settling.

Response: { totalBalance: number, currency: string } (default currency 'cash').

Theming

Match the embed to your brand. The embed always starts from the ProphetX dark palette; your theme changes it from there. There is no light/dark flag: a light look is a full light palette in colorOverrides. The Theming Guide has the light palette, every token, and the Theme Playground.

// On the provider (React, React Native, Flutter): applies to every flow
<ProphetXProvider
  environment="production"
  token={jwt}
  theme={{
    colorOverrides: { primary: '#4F46E5', primaryHover: '#4338CA', cta: '#4F46E5', ctaHover: '#4338CA' },
    radiusOverrides: { sm: '4px', md: '8px', lg: '16px' },
  }}
>...
// Vanilla JS: pass it on each open, or change it while a flow is open
px.openDeposit({ token, theme: { primaryColor: '#4F46E5' } });
px.updateTheme({ primaryColor: '#7C3AED' });
  • primaryColor sets the four action colors, but only when colorOverrides is empty. Once you send colorOverrides, put the action colors there.
  • React: changing the theme prop re-sends it to an open modal only when primaryColor or backgroundColor changes. Other changes apply the next time a flow opens. React Native and Flutter re-send on any change.
  • Vanilla JS: updateTheme() does nothing when no flow is open, and the theme isn't kept for the next flow.

Full ThemePayload shape:

type ThemePayload = {
  primaryColor?: string;      // ignored when colorOverrides has keys
  backgroundColor?: string;   // React Native and Flutter only: the native modal's background
  colorOverrides?: { primary?: string; surface?: string; text?: string; /* 28 color tokens */ };
  spacingOverrides?: { xs?: string; sm?: string; md?: string; lg?: string; xl?: string };
  radiusOverrides?: { sm?: string; md?: string; lg?: string; full?: string };
  fontSizeOverrides?: { xs?: string; sm?: string; md?: string; lg?: string; xl?: string };
};

Localization

The embed is available in English (en, the default) and Spanish (es). Set the language once:

// React, React Native, Flutter: on the provider
<ProphetXProvider environment="production" token={jwt} locale="es">...</ProphetXProvider>
// Vanilla JS: on each open, or change it while a flow is open
px.openDeposit({ token, locale: 'es' });
px.updateLocale('en');
  • A region subtag is dropped (es-MX becomes es), and any other language falls back to English.
  • The embed switches its text as soon as the locale arrives; nothing reloads.
  • Text you supply yourself, such as successButtonLabel, is shown exactly as you pass it and isn't translated.
  • In 1-Click Signup, everything before the outcome is Verified's own screen, which locale doesn't reach; it applies only to the embed's three outcome screens.

Events

Subscribe once and react to anything the embed emits — perfect for analytics or error reporting.

// React
import { useEvents } from '@prophetx/sdk-react';

function Analytics() {
  useEvents({
    onReady:          ()     => analytics.track('embed_ready'),
    onSuccess:        (d)    => analytics.track('flow_success', d),
    onError:          (d)    => errorReporter.capture('flow_error', d),
    onCancel:         ()     => analytics.track('flow_cancel'),
    onGeofenceBlocked:(d)    => analytics.track('geofence_block', d),
    onKycSuccess:     (d)    => analytics.track('kyc_success', d),
    onKycFailed:      (d)    => analytics.track('kyc_failed', d),
    onKycPending:     ()     => analytics.track('kyc_pending'),
    onOneClickSuccess:(d)    => analytics.track('one_click_success', d),
    onOneClickFailed: (d)    => analytics.track('one_click_failed', d),
    onOneClickDeclined:()    => analytics.track('one_click_declined'),
  });
  return null;
}
// Vanilla JS
const unsub = px.on('success', (d) => analytics.track('deposit_success', d));
px.on('error',   (d) => errorReporter.capture('sdk_error', d));
px.on('open',    (d) => analytics.track('flow_open', { flow: d.flow }));
px.on('close',   (d) => analytics.track('flow_close', { flow: d.flow }));
unsub();

All events:

EventPayload
ready—
success{ transactionId, amount? }
successAction— (the user pressed the success button)
error{ code, message } — also SESSION_REFRESH_FAILED when your onSessionExpired throws
cancel—
kycSuccess{ identityUuid? } (always absent)
kycFailed{ reason, retryable? }
kycPending—
oneClickSuccess{ identityUuid }
oneClickFailed{ reason, retryable? }
oneClickDeclined—
geofenceBlocked{ stateCode, reason }
resize{ height }
sessionExpired—
sessionRefreshed{ token }
open / close{ flow } — the route path: 'deposit', 'withdraw', 'verified' (from useKyc), 'id-upload', 'one-click-signup', 'onboarding'

Geofence

US betting regulation varies by state. The embed checks the user's location in two places, so handle both:

  1. When the flow opens. If the user's token says their location check didn't pass, the embed shows its own blocked screen and fires onGeofenceBlocked(stateCode, reason). Both arguments are currently always 'unknown', so don't branch on them or show them; use your own copy.
  2. Just before a deposit or withdrawal is submitted. The embed re-validates the session. If that fails it fires onError('GEOFENCE_BLOCKED', message) instead. The check fails closed, so a token that expired while the user sat on the form also lands here. Reopen the flow with a fresh token before showing location messaging.
deposit.open({
  onGeofenceBlocked: () => showStateUnavailable(),
  onError: (code) => {
    if (code === 'GEOFENCE_BLOCKED') reopenWithFreshToken();
  },
});

There is no VPN detection; location comes from the token your backend mints. You can also subscribe globally via on('geofenceBlocked', ...) / useEvents({ onGeofenceBlocked }).

Session refresh

Provide an onSessionExpired handler that asks your backend for a fresh token and returns it (or null to abort):

<ProphetXProvider
  environment="production"
  token={jwt}
  onSessionExpired={async () => {
    const res  = await fetch('/api/auth/refresh');
    const data = await res.json();
    return data.token;  // return null to abort
  }}
>...
px.openDeposit({
  token: jwt,
  onSessionExpired: async () => (await refresh()).token,
});

DevTools

Toggle-on debug logging with PII redaction. Off by default.

<ProphetXProvider
  environment="staging"
  devtools={{
    enabled: true,
    logLevel: 'debug',           // 'none' | 'error' | 'warn' | 'info' | 'debug'
    redactPII: true,             // default true; masks tokens, emails, passwords
    onEvent: (entry) => myLogger.log(entry.category, entry.message, entry.data),
  }}
>...

Categories: auth (purple), message (blue), api (green), lifecycle (amber), event (pink). With redactPII on, tokens / passwords / emails appear as [REDACTED] in logs.


9. Environments

EnvironmentEmbed URLAPI Base URL
productionhttps://embed.prophetx.cohttps://isv-api.prophetx.co
staginghttps://isv-embed-fe-embed.vercel.apphttps://isv-api.staging.prophetx.dev
sandboxhttps://isv-embed-fe-embed-sandbox.vercel.apphttps://isv-api.sandbox.prophetx.dev
// Preset (recommended)
createProphetX({ environment: 'staging' });
<ProphetXProvider environment="staging" .../>

// Custom (point at your own deploys)
createProphetX({
  environment: { embedUrl: 'https://embed.example.com', apiBaseUrl: 'https://api.example.com' },
});
📘

Start in sandbox, promote through staging, then go live in production. Your allow-listed origins must be configured by ProphetX before production traffic will work.


10. Lifecycle & Cleanup

React / React Native / Flutter: cleanup is automatic when the provider unmounts. Nothing extra to do.

Vanilla JS: call destroy() when you're done with the SDK instance (typically on page unload). This tears down the iframe, removes listeners, and stops auth timers. After destroy() the instance is unusable.

px.close();    // close the active flow modal
px.destroy();  // tear the whole SDK down

11. Error Codes

CodeWhereMeaning
DEPOSIT_FAILEDonError in depositGeneric deposit failure (fallback — check for a provider-specific code first)
WITHDRAWAL_FAILEDonError in withdrawGeneric withdrawal failure (fallback)
KYC_REQUIREDonError in withdraw onlyThe embed handles it, but the backend doesn't send it today — see Error Codes.
GEOFENCE_BLOCKEDonError in deposit/withdrawThe pre-submit location re-check failed. Also fires when the session couldn't be re-validated (for example, the token expired on the form). Reopen with a fresh token.
onGeofenceBlockedDedicated callback, not onErrorThe user's location blocks the flow when it opens. Never fires on 1-Click Signup. Both arguments are currently 'unknown'.
SESSION_EXPIREDonErrorThe token was already expired when the flow opened. The flow can't recover; close it and open it again with a fresh token.
SESSION_INVALIDonErrorToken rejected by server
ORIGIN_UNAUTHORIZEDonErrorEmbedding origin isn't allow-listed
INVALID_CREDENTIALSauth.loginWrong email/password
NETWORK_ERRORauth.loginNetwork unreachable
SERVER_ERRORauth.login5xx from auth endpoint
TIMEOUTauth.loginRequest timed out

A user who hasn't completed an onboarding gate gets no error: the deposit and withdraw screens open with only the methods their token permits (often just Wire Transfer). Check gate status on your backend before opening a flow.

See Error Codes for the full reference, including the real provider-specific codes (aeropay_rejected, pnm_rejected, amount_mismatch, etc.) that a DEPOSIT_FAILED/WITHDRAWAL_FAILED fallback may be masking.


12. API Reference Cheat Sheet

React (@prophetx/sdk-react)

<ProphetXProvider
  environment? : 'production' | 'staging' | 'sandbox' | EnvironmentConfig
  token?       : string                                // omit when using `auth`
  theme?       : EmbedTheme
  locale?      : string                                // 'en' (default) or 'es'
  auth?        : { apiBaseUrl: string, getCredentials?: () => LoginCredentials | Promise<LoginCredentials>,
                   refreshBufferSeconds?: number, onAuthStateChanged?: (state: AuthState) => void }
  devtools?    : DevToolsConfig
  attributionVariant? : 'logo' | 'text'              // no effect against a deployed embed today
  onSessionExpired? : () => Promise<string | null>
  embedUrl?    : string                                // deprecated — use environment
>

// Flow hooks
useDeposit():        { open(opts?), close(), isOpen }
useWithdraw():       { open(opts?), close(), isOpen }
useOneClickSignup(): { open(opts), close(), isOpen }   // opts required — needs sessionKey
useKyc() / useIdUpload(): { open(opts?), close(), isOpen }  // same flow, two names

// Module hooks
useAuth():   { state, login, logout, token, isAuthenticated }   // throws without the `auth` prop
useWallet(): { balance, loading, error, refetch }              // throws without `environment`; call refetch() to load
useEvents(handlers): void

Vanilla JS (@prophetx/sdk-js)

createProphetX({ environment?, auth?, devtools?, attributionVariant?, embedUrl? /* deprecated */ }): SDKInstance

type SDKInstance = {
  openDeposit(opts):        void;
  openWithdraw(opts):       void;
  openOnboarding(opts):     void;  // opens the gated error screen — see the 1-Click Signup warning above
  openOneClickSignup(opts): void;  // opts required — needs sessionKey/environment
  openKyc(opts):            void;  // historical alias
  openIdUpload(opts):       void;  // same flow as openKyc, preferred name
  close():       void;
  destroy():     void;
  updateTheme(theme):  void;   // only while a flow is open
  updateLocale(locale): void;  // only while a flow is open
  on(event, handler):  () => void;
  off(event, handler): void;
  auth:   AuthManager  | null;   // null until `auth` configured
  wallet: WalletClient | null;   // null unless both `auth` and `environment` are set
};

Options shared by all flows

These are the Vanilla JS option types. React, React Native and Flutter take the same callbacks on open(), but token, theme, locale and onSessionExpired go on the provider instead.

// openDeposit / openWithdraw
type OpenOptions = {
  token?: string;                                // not needed with the auth module
  theme?: EmbedTheme;
  locale?: string;
  initialAmount?: number;
  successButtonLabel?: string;                   // at most 40 characters, not translated
  onSuccessAction?: () => void;
  onReady?: () => void;
  onSuccess?: (transactionId: string, amount?: number) => void;
  onError?:   (code: string, message: string) => void;
  onCancel?:  () => void;
  onGeofenceBlocked?: (stateCode: string, reason: string) => void;
  onSessionExpired?:  () => Promise<string | null>;
};

// openIdUpload / openKyc / openOnboarding
type KycOpenOptions = {
  token?: string;
  theme?: EmbedTheme;
  locale?: string;
  redirectUrl?: string;                          // same-origin URL or app scheme
  onKycSuccess?: (identityUuid?: string) => void; // identityUuid is always absent
  onKycFailed?:  (reason: string, retryable?: boolean) => void; // always final
  onKycPending?: () => void;
  onReady?: () => void;
  onError?:   (code: string, message: string) => void;
  onCancel?:  () => void;
  onGeofenceBlocked?: (stateCode: string, reason: string) => void;
  onSessionExpired?:  () => Promise<string | null>;
  // also accepts onOneClickSuccess / onOneClickFailed / onOneClickDeclined
};

// openOneClickSignup
type OneClickOpenOptions = Omit<KycOpenOptions, 'token' | 'redirectUrl' | 'onSessionExpired'> & {
  sessionKey: string;                            // from POST /private/v1/one-click/sessions
  environment: 'sandbox' | 'production';
};

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

Same API as @prophetx/sdk-react, plus appLink on deposit and withdraw. The provider renders a full-screen native Modal with a WebView. ProphetXWebView and ProphetXModal are exported for advanced custom chrome (see the API Reference).

Flutter (prophetx_sdk)

ProphetXProvider(                                  // mount inside MaterialApp
  environment: EnvironmentName.production,         // or EnvironmentConfig(...)
  token: jwt,
  theme: const EmbedTheme(primaryColor: '#4F46E5'),
  locale: 'en',
  attributionVariant: PoweredByVariant.logo,      // no effect against a deployed embed today
  child: const HomeScreen(),
);

final px = ProphetX.of(context);
px.deposit.open(OpenDepositOptions(onSuccess: ...));
px.withdraw.open(...);
px.idUpload.open(...);                            // or px.kyc — same flow
px.oneClickSignup.open(OpenOneClickSignupOptions(sessionKey: ..., environment: ...));
// px.onboarding exists, but the flow is permanently unavailable

px.wallet?.refetch();
px.events.stream.listen((event) { ... });   // ReadyEvent | SuccessEvent | ...

13. FAQ & Troubleshooting

Q: Do I need to embed AeroPay / ZeroHash / PayNearMe SDKs?
No. The ProphetX embed loads them itself.

Q: The embed isn't rendering — I get a blank modal.
Most common cause: your origin isn't on ProphetX's allow-list. Contact your ProphetX integration contact and confirm window.location.origin. In dev, also confirm you're pointing at the right environment.

Q: I keep getting SESSION_EXPIRED.
SESSION_EXPIRED means the token was already expired when the flow opened, so mint the token right before you open the flow. To keep a flow alive past expiry, implement onSessionExpired to return a fresh token from your backend.

Q: How do I detect when the user closed the modal vs. completed?
onSuccess fires when the deposit or withdrawal completes, but the modal stays open on the embed's own success screen. When the user then closes it, onCancel fires too. So treat onSuccess as "it happened" and onCancel as "the modal is gone". If you pass onSuccessAction, the success button calls it and closes the modal instead, and onCancel doesn't fire for that path. Don't close the modal yourself on onSuccess or onError; the embed shows a success or retry screen.

Q: Can I show my own loading state before the embed shows?
Yes — keep your own spinner up until onReady fires.

Q: How do I customize the modal chrome on mobile?
For RN, the default ProphetXProvider renders ProphetXModal for you. To swap in your own header / presentation, use the lower-level ProphetXWebView directly. Flutter has the same pattern with ProphetXWebView.

Q: What if my user is on a VPN?
The embed doesn't detect VPNs. Location comes from the token your backend mints, and a blocked user gets onGeofenceBlocked('unknown', 'unknown'). Show your own message and don't auto-retry.

Q: AeroPay asks for an SMS code in sandbox but nobody receives it.
The code is a real text from AeroPay, sent to the phoneNumber on the user's ProphetX record, so test users with placeholder numbers never get one. In sandbox, enter 000000 — it is always accepted. Being asked for the code again on a later visit is expected: AeroPay periodically expires the per-user session and the embed re-runs the SMS check. Production has no bypass code.

Q: The bank-linking widget shows an error like INSTITUTION_ERROR / AC-148.
That text is Aerosync's own error, shown inside its bank-linking widget, raised after ProphetX has already issued a valid session. It isn't sent to your page; if the link fails, the embed shows its own "AeroPay unavailable" screen. It usually tracks an incident on AeroPay's side. Retry; if it persists, send your ProphetX contact the user id and timestamp so we can raise it with AeroPay. For sandbox bank linking, use the test bank Aerobank with username sync and password no_mfa.

Q: Where do I send sensitive analytics — through useEvents or my own backend?
Either, but useEvents already passes you only the event payloads (no raw tokens or PII). The built-in DevTools also redact PII before logging.

Q: How do I switch the theme to match a dark/light toggle in my app?
Keep two complete palettes and pass one to theme (see the Theming Guide). React Native and Flutter update an open flow live. React updates an open modal only when primaryColor or backgroundColor changes; a palette swap applies the next time a flow opens. In Vanilla JS, call px.updateTheme(...) while the flow is open.

Q: Can I run two flows at once?
No — opening a second flow closes the first one. This is intentional to keep the user's attention on one transaction at a time.


Support resources

  • Live demo — isv-embed-fe-mock-isv-host.vercel.app, a mock ISV host app with all flows wired up (Staging by default, Sandbox from its Dev Settings)
  • Status page — https://status.prophetx.co (ask your contact for the right URL for your tenant)
  • Partner support — reach out through your ProphetX integration channel
  • SDK source — available on request for security review


Did this page help you?