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 back FAILURE.
  • Terms acceptance — there's no SDK hook for this; you host /tandc yourself in a raw iframe.

What you'll do

  1. Set up the SDK — install and configure the ProphetX SDK for your stack.
  2. Open a deposit — let them fund their account via your frontend.
  3. View transaction history — show users their recent transactions and statuses.
  4. Display the balance — show the user's current wallet balance.
  5. 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-react

Then 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 Prerequisites

When 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 needs kyc, terms, email-verify and not-suspended, so a user who has only to accept terms still sees just Wire Transfer. onError doesn't fire.

So check the user's gates on your backend before you open the flow, and route them first:

  • kyc not complete — this user already exists (they hold an embed token), so route them to useKyc/useIdUpload (document verification), not useOneClickSignup (that's only for creating a brand-new user, before any token exists).
  • terms not complete — show the /tandc route (see Terms flow).
  • email-verify / phone-verify not complete — there's no embedded flow; handle these on your side (re-send verification email, OTP UI).
  • not-suspended not 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.

Full prerequisite reference →

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:

OptionWhat it does
initialAmountPre-fills the amount. The user can still change it.
successButtonLabelReplaces the success screen's "Make Another Deposit" button text (at most 40 characters, shown exactly as given).
onSuccessActionCalled 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.
onReadyThe deposit screen has rendered.
appLinkReact 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 in onSuccess

Cash at Retail ends when the user leaves with a barcode, and Wire Transfer only shows instructions; both end with onCancel. And onSuccess can arrive while the payment is still settling. So refresh the user's balance after onCancel as well as after onSuccess, 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 surface onError("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 completed kyc gate isn't offered Online Bank at all. See Error Codes. If it fires, open useKyc/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 missing

If only terms is pending, show the /tandc route (see Terms flow) for just the T&C acceptance screen. If kyc is pending — this only happens for a user re-verifying after an earlier automated FAILURE, since a session token implies a ProphetX user already exists — useKyc/useIdUpload opens 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), or onKycFailed (the user can't verify through this flow; always final). Build your retry-withdrawal prompt off onKycSuccess only.

Full flow reference →

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 onSuccess fires. 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


Did this page help you?