Deposits and Withdrawals
Integrate the ProphetX Wallet so users can deposit and withdraw funds.
Upfront verification and terms (optional)This guide walks through a just-in-time pattern — users are prompted to accept ProphetX's terms and complete identity verification the first time they open a deposit or withdrawal. If you prefer, you can run these steps upfront during your registration flow so the wallet flows open straight into the modal.
useOneClickSignup— for a brand-new user: creates the ProphetX user from a phone number. There is no bundled first-deposit option — trigger a deposit separately afterward if you want that.useKyc/useIdUpload— for an existing user whose automated KYC came backFAILURE.- Terms acceptance — there's no SDK hook for this; you host
/tandcyourself in a raw iframe.
What you'll do
- Set up the SDK — install and configure the ProphetX SDK for your stack.
- Open a deposit — let them fund their account via your frontend.
- View transaction history — show users their recent transactions and statuses.
- Display the balance — show the user's current wallet balance.
- Add withdrawals — let them withdraw funds.
Before you begin
Complete the User Setup guide first — you'll need a created and verified ProphetX user before continuing.
Complete the Session Token Setup guide — your backend signs short-lived JWTs that authorize the embed to act on behalf of each user.
Step 1: Set up the SDK
Install the package for your stack:
npm install @prophetx/sdk-reactThen set up the provider:
The ProphetXProvider wraps your component tree. The token prop is optional — you can mount the provider at app startup and pass the token once it's available. The SDK passes it to the iframe when any flow opens. If the token expires mid-flow, onSessionExpired lets you return a fresh one. Optional theme and locale props let you brand the embed and switch language ("en" or "es").
import { useState, useEffect, useCallback } from "react";
import { ProphetXProvider } from "@prophetx/sdk-react";
import { App } from "./App";
export function Root() {
const [token, setToken] = useState<string>();
// Calls YOUR backend token endpoint.
const refreshToken = useCallback(async () => {
const res = await fetch("/api/prophetx-token");
const { token } = await res.json();
setToken(token);
return token;
}, []);
useEffect(() => { refreshToken() }, [refreshToken]);
return (
<ProphetXProvider
environment="sandbox" // "production" | "staging" | "sandbox"
token={token}
onSessionExpired={refreshToken}
>
<App />
</ProphetXProvider>
);
}Step 2: Open a deposit
With the provider in place, opening a deposit is a single function call. The SDK renders a modal that handles the full deposit flow. When the deposit is accepted, onSuccess fires with a transactionId and amount — store the transactionId on your backend. The modal then stays open on the embed's success screen, and onCancel fires when the user closes it.
User PrerequisitesWhen the embed opens it validates the user's token and its gates (
kyc,terms,email-verify,phone-verify,not-suspended). KYC is not exempt — a session token alone does not imply KYC is complete. An unmet gate does not produce an error: the backend marks the affected payment permissions as not granted, and the deposit screen opens with only the methods still granted. Every method except Wire Transfer needskyc,terms,email-verifyandnot-suspended, so a user who has only to accept terms still sees just Wire Transfer.onErrordoesn't fire.So check the user's gates on your backend before you open the flow, and route them first:
kycnot complete — this user already exists (they hold an embed token), so route them touseKyc/useIdUpload(document verification), notuseOneClickSignup(that's only for creating a brand-new user, before any token exists).termsnot complete — show the/tandcroute (see Terms flow).email-verify/phone-verifynot complete — there's no embedded flow; handle these on your side (re-send verification email, OTP UI).not-suspendednot complete — not user-resolvable; direct the user to support.Location is checked when the flow opens (
onGeofenceBlocked, both arguments currently'unknown') and again just before the deposit is submitted (onError('GEOFENCE_BLOCKED', message)). The second check fails closed, so it also fires if the token expired while the user was on the form; reopen with a fresh token.
import { useDeposit } from "@prophetx/sdk-react";
export function DepositButton() {
const { open, close, isOpen } = useDeposit();
return (
<button
onClick={() =>
open({
initialAmount: 25.00, // optional — prefills the modal; the user can still edit it
onSuccess: (transactionId, amount) => {
console.log("Deposited", amount, "tx:", transactionId);
},
onError: (code, message) => {
console.error("Deposit error:", code, message);
},
})
}
>
Deposit
</button>
);
}Deposit options
Besides the callbacks above, open() takes:
| Option | What it does |
|---|---|
initialAmount | Pre-fills the amount. The user can still change it. |
successButtonLabel | Replaces the success screen's "Make Another Deposit" button text (at most 40 characters, shown exactly as given). |
onSuccessAction | Called when the user presses that button; the modal then closes, and onCancel doesn't fire. Use it to send the user on, for example to your trading screen. |
onReady | The deposit screen has rendered. |
appLink | React Native and Flutter only. Your app's bare URL scheme, e.g. myapp://. Without it, a user linking a bank that logs in with OAuth is stuck on "Almost there!" after the bank login, and Apple Pay and Google Pay can't return to your app. Register the scheme and handle the incoming link without navigating — see Returning to your app. |
The full list, with types, is in the API Reference.
Not every deposit ends inonSuccessCash at Retail ends when the user leaves with a barcode, and Wire Transfer only shows instructions; both end with
onCancel. AndonSuccesscan arrive while the payment is still settling. So refresh the user's balance afteronCancelas well as afteronSuccess, and treat the wallet balance as the source of truth for whether money arrived.
Step 3: View transaction history
Once a user completes a deposit or withdrawal, you'll want to give them visibility into their recent transactions — including the current status of each one.
Rather than exposing this through the SDK, transaction history is served directly by the ProphetX backend, server-to-server — there is no embed-facing transactions endpoint. Your server calls GET /private/v1/transactions, then returns the results to your client to render in your UI. See Wallets for the full request/response shape, pagination, and the TransactionType enum.
To find the ledger rows for a flow, match the transactionId from onSuccess against each row's txId. Don't filter with the refId query parameter: refId references market and parlay orders, so it never matches a deposit or withdrawal. The match works for Online Bank, Crypto and PayNearMe withdrawals. PayNearMe deposits (debit card, Apple Pay, Google Pay, cash) are the exception: the backend generates their txId, so the embed's transactionId won't match. For those, read the wallet balance or list recent transactions instead.
Step 4: Display the balance
Use the wallet hook to fetch and display the user's current balance. refetch is manual — call it on mount and after any deposit or withdrawal completes.
import { useEffect } from "react";
import { useWallet } from "@prophetx/sdk-react";
export function BalanceDisplay() {
const { balance, loading, error, refetch } = useWallet();
useEffect(() => { refetch() }, [refetch]);
if (loading) return <p>Loading...</p>;
if (error) return <p>Failed to load balance.</p>;
return (
<p>{balance ? `${balance.totalBalance} ${balance.currency}` : "—"}</p>
);
}Step 5: Add withdrawals
Withdrawals follow the same pattern as deposits — same open() call, same callbacks, and the same prerequisites described in Step 2. As with deposits, an unmet gate produces no error: the withdraw screen opens with only the methods the user's token still permits. Check gates on your backend before opening the flow.
Withdraw specifically may also surfaceonError("KYC_REQUIRED", message)— the embed shows a "Verification required" screen when an Online Bank withdrawal is refused because the user's identity isn't verified. The backend doesn't send it today: a user without a completedkycgate isn't offered Online Bank at all. See Error Codes. If it fires, openuseKyc/useIdUpload(this user already exists, so it's re-verification, not signup), then let the user retry the withdrawal.
import { useWithdraw } from "@prophetx/sdk-react";
export function WithdrawButton() {
const { open, close, isOpen } = useWithdraw();
return (
<button
onClick={() =>
open({
initialAmount: 25.00, // optional — prefills the modal; the user can still edit it
onSuccess: (transactionId, amount) => {
console.log("Withdrew", amount, "tx:", transactionId);
},
onError: (code, message) => {
console.error("Withdraw error:", code, message);
},
})
}
>
Withdraw
</button>
);
}
What your user sees when a gate is missingIf only
termsis pending, show the/tandcroute (see Terms flow) for just the T&C acceptance screen. Ifkycis pending — this only happens for a user re-verifying after an earlier automatedFAILURE, since a session token implies a ProphetX user already exists —useKyc/useIdUploadopens IDComply's document-upload flow in a second browser tab, not a phone/OTP screen.Document verification terminates with one of three callbacks:
onKycSuccess(verified, or already verified — final, no further async step),onKycPending(still under review), oronKycFailed(the user can't verify through this flow; always final). Build your retry-withdrawal prompt offonKycSuccessonly.
Withdrawal errors and outcomes
Withdrawals have their own error codes — WITHDRAWAL_FAILED, WITHDRAWAL_UNCONFIRMED, WITHDRAWAL_NOT_COMPLETED, WITHDRAWAL_WALLET_WRITE_FAILED, PAYNEARME_WITHDRAWAL_FAILED, KYC_REQUIRED, PROVIDER_ERROR, ZEROHASH_PROVIDER_ERROR and GEOFENCE_BLOCKED. The withdrawal table says what the embed shows after each and what to do.
- A user with less than $1 available can't start a withdrawal: the embed tells them, and the flow ends with
onCancel, not an error. - A withdrawal to a debit card is held for review when
onSuccessfires. The amount has left the ProphetX balance; it goes back if the review rejects it.
Once a user has cleared verification and accepted T&C, the kyc and terms gates report completed: true, and future deposits and withdrawals open with every payment method their account allows. ProphetX tracks verification state on the backend — you don't need to cache or check it yourself.
Next steps
Now that you have a working integration, explore these guides to polish it:
- Payment Methods — every method, its limits, and what your app has to set up
- API Reference — full props, hooks, and types for all four SDKs
- Theming Guide — customize colors, light or dark palettes, and CSS variables
- postMessage Protocol — low-level event reference for custom integrations
- Error Codes — every error code, what causes it, and what to do
Updated 5 days ago
