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

Your partner account is configured with API deposit flow (contact your Oobit account manager)
You pass email (and optionally externalUserId) to the widget to identify the user
When the user taps "Add Funds" in the widget, the onDepositRequested callback fires
Your app navigates the user to your own deposit page
Your backend calls the Get Deposit Address API to fetch a deposit address
The user sends crypto to that address

SDK Integration

Pass email (required) to link the widget user to your API user. Optionally, pass externalUserId as an alternative identifier for future API calls. Then handle the onDepositRequested callback.

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

function WidgetPage() {
  return (
    <WidgetSDK
      accessToken={tokenFromBackend}
      email="[email protected]"
      externalUserId="your-internal-user-id" // optional
      onDepositRequested={() => {
        // Navigate to your custom deposit page
        router.push("/deposit");
      }}
    />
  );
}

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

function WidgetScreen() {
  return (
    <WidgetSDK
      accessToken={tokenFromBackend}
      email="[email protected]"
      externalUserId="your-internal-user-id" // optional
      onDepositRequested={() => {
        // Navigate to your custom deposit page
        navigation.navigate("Deposit");
      }}
    />
  );
}

User Identification

The email prop is required for API-Managed Deposits — it links the widget session to a user in the Oobit system. You can optionally pass externalUserId as well, which lets you use your own internal ID instead of the user's email when calling the API.

Prop	Required	Description
`email`	Yes	User's email address. Required to identify the user
`externalUserId`	No	Your internal user ID. Can be used instead of email in future API calls

Important: The email must always be provided when using API-Managed Deposits. If you also provide externalUserId, you can use either identifier when calling the Get Deposit Address API.

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

Status	Meaning	Deposits	How to handle
`PENDING`	User is still going through onboarding (KYC, etc.)	❌	Transient — poll status, or prompt the user to continue onboarding
`ACTIVE`	User is fully onboarded and eligible for deposits	✅	Fetch the deposit address
`REJECTED`	User cannot be onboarded (compliance, geo, etc.)	❌	Terminal — surface a clear error; waiting or retrying will not change this