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:
| Stack | Package | Install |
|---|---|---|
| React (web) | @prophetx/sdk-react | npm i @prophetx/sdk-react |
| Vanilla JS | @prophetx/sdk-js | npm i @prophetx/sdk-js |
| React Native | @prophetx/sdk-react-native | npm i @prophetx/sdk-react-native react-native-webview @react-native-async-storage/async-storage |
| Flutter | prophetx_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
- What You Get
- Before You Start
- Quick Start (React)
- Quick Start (Vanilla JS)
- Quick Start (React Native)
- Quick Start (Flutter)
- Available Flows
- Built-In Modules
- Environments
- Lifecycle & Cleanup
- Error Codes
- API Reference Cheat Sheet
- FAQ & Troubleshooting
1. What You Get
Four end-user flows, fully implemented and hosted by ProphetX:
| Flow | What the user does |
|---|---|
| Deposit | Picks 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. |
| Withdraw | Enters 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:
- Create a ProphetX partner account — talk to ProphetX onboarding to get your sandbox/staging credentials.
- Provide a session JWT for each user — your backend mints an embed token with
GET /private/v1/tokensand passes it to your frontend — see Embedded UI. 1-Click Signup uses a session key fromPOST /private/v1/one-click/sessionsinstead — see Identity Verification. - Allow-list your origins — coordinate with ProphetX before going live so your production domains can render the embed.
- 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-reactWrap 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-jsimport { 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 onlyPeer 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
NSAppTransportSecurityis not blocking HTTPS (iOS).
6. Quick Start (Flutter)
Add to pubspec.yaml:
dependencies:
prophetx_sdk: ^0.5.0prophetx_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)
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). UseuseOneClickSignupfor 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 theauthmodule 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' });primaryColorsets the four action colors, but only whencolorOverridesis empty. Once you sendcolorOverrides, put the action colors there.- React: changing the
themeprop re-sends it to an open modal only whenprimaryColororbackgroundColorchanges. 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-MXbecomeses), 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
localedoesn'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:
| Event | Payload |
|---|---|
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:
- 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. - 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
| Environment | Embed URL | API Base URL |
|---|---|---|
production | https://embed.prophetx.co | https://isv-api.prophetx.co |
staging | https://isv-embed-fe-embed.vercel.app | https://isv-api.staging.prophetx.dev |
sandbox | https://isv-embed-fe-embed-sandbox.vercel.app | https://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 throughstaging, then go live inproduction. 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 down11. Error Codes
| Code | Where | Meaning |
|---|---|---|
DEPOSIT_FAILED | onError in deposit | Generic deposit failure (fallback — check for a provider-specific code first) |
WITHDRAWAL_FAILED | onError in withdraw | Generic withdrawal failure (fallback) |
KYC_REQUIRED | onError in withdraw only | The embed handles it, but the backend doesn't send it today — see Error Codes. |
GEOFENCE_BLOCKED | onError in deposit/withdraw | The 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. |
onGeofenceBlocked | Dedicated callback, not onError | The user's location blocks the flow when it opens. Never fires on 1-Click Signup. Both arguments are currently 'unknown'. |
SESSION_EXPIRED | onError | The token was already expired when the flow opened. The flow can't recover; close it and open it again with a fresh token. |
SESSION_INVALID | onError | Token rejected by server |
ORIGIN_UNAUTHORIZED | onError | Embedding origin isn't allow-listed |
INVALID_CREDENTIALS | auth.login | Wrong email/password |
NETWORK_ERROR | auth.login | Network unreachable |
SERVER_ERROR | auth.login | 5xx from auth endpoint |
TIMEOUT | auth.login | Request 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)
@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): voidVanilla JS (@prophetx/sdk-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)
@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)
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
Updated 5 days ago
