API-Managed Deposits

By default, the Plug & Pay widget handles the entire deposit flow — the user selects a token, picks a network, and sends crypto directly through the widget. API-Managed Deposits is for partners who want to manage deposits themselves, using their own deposit UI and the Oobit Partner API.

When to Use

Use API-Managed Deposits if you want to:

• Build a custom deposit experience in your app
• Control which tokens and networks are shown to the user
• Support more chains and tokens than Widget-Managed Deposits — use the List Crypto Currencies API to see the full list
• Use your own transaction signing flow for deposits

How It Works

1. Your partner account is configured with API deposit flow (contact your Oobit account manager)
2. (Optional) You pass email and/or externalUserId to the widget. If you don't pass email, the user enters and verifies it inside the widget's onboarding flow.
3. When the user taps "Add Funds" in the widget, the onDepositRequested(email) callback fires — the SDK forwards the user's verified email so your app always has it
4. Your app navigates the user to your own deposit page
5. Your backend calls the Get Deposit Address API using email (or externalUserId) to fetch a deposit address
6. The user sends crypto to that address

SDK Integration

email is optional. Pass it if you already know the user's email — the widget will skip email entry and prefill it. Otherwise, the user enters and verifies their email inside the widget's onboarding flow. Either way, the SDK forwards the user's verified email to onDepositRequested(email) so your app can identify them when calling the Partner API.

You can optionally pass externalUserId as an alternative identifier for Partner API calls.

import { WidgetSDK, type StandaloneConfig } from "@oobit/react-web";

function WidgetPage() {
  return (
    <WidgetSDK
      accessToken={tokenFromBackend}
      email="[email protected]" // optional - prefills onboarding
      externalUserId="your-internal-user-id" // optional
      onDepositRequested={(email) => {
        // `email` is the user's verified email — use it to call the Partner API
        router.push(`/deposit?email=${encodeURIComponent(email)}`);
      }}
    />
  );
}

import { WidgetSDK, type StandaloneConfig } from "@oobit/react-native-sdk";

function WidgetScreen() {
  return (
    <WidgetSDK
      accessToken={tokenFromBackend}
      email="[email protected]" // optional - prefills onboarding
      externalUserId="your-internal-user-id" // optional
      onDepositRequested={(email) => {
        // `email` is the user's verified email — use it to call the Partner API
        navigation.navigate("Deposit", { email });
      }}
    />
  );
}

User Identification

Both email and externalUserId are optional inputs to the SDK. Whichever path the user takes — host-supplied email or in-widget onboarding — the verified email is delivered back to your app via onDepositRequested(email), so you always have an identifier for Partner API calls.

Important: When onDepositRequested(email) fires, the user has completed email verification — that email can be used immediately as an identifier for the Get Deposit Address API. If you also provided externalUserId, you can use either identifier.

Backend: Fetching Deposit Addresses

When the user lands on your deposit page, use the Get Deposit Address API from your backend to fetch a deposit address for the user. You can identify the user by email or externalUserId.

Use the List Supported Crypto Currencies API to get available currencies and networks to present to the user.

Important: The user must complete onboarding inside the widget before you can fetch a deposit address for them. Until the user is ACTIVE, the Get Deposit Address API will not return an address.

Use the Get User Status API to check where the user is. The response includes a status field and a depositsAllowed flag — depositsAllowed is true only when status is ACTIVE.

User Statuses

See Also

• Deposit Flow — Overview of both deposit modes
• Widget-Managed Deposits — The alternative mode
• Get Deposit Address API — API reference
• List Crypto Currencies API — Available currencies and networks