Prerequisites

• The user must exist — call POST /v1/users:upsert on sign-in and store the returned id.
• You need a V1 API key issued by Uptop. The API key stays on your server — it is exchanged for a short-lived token before the iframe URL is constructed.

Authentication

Your backend exchanges the API key for a short-lived JWT and passes it to the client as iframeToken. The API key never leaves your server.

// Exchange API key for a short-lived iframe token (10 min)
const { accessToken } = await fetch(
  `${UPTOP_API_BASE}/v1/users/${userId}/auth/client-token`,
  { method: 'POST', headers: { 'Api-Key': process.env.UPTOP_API_KEY } }
).then(r => r.json());

// Return accessToken to the client — never the raw API key
return { iframeToken: accessToken };

Embed Code

Two separate screens in your app, two iframe URLs. Both take the same userId and iframeToken, so one token fetch covers both.

<iframe
  src="https://insomniac-docs.uptop.xyz/embed/add-funds?userId={USER_ID}&iframeToken={TOKEN}"
  width="390"
  height="844"
  style="border:none;"
  allow="payment"
></iframe>

<iframe
  src="https://insomniac-docs.uptop.xyz/embed/withdraw?userId={USER_ID}&iframeToken={TOKEN}"
  width="390"
  height="844"
  style="border:none;"
></iframe>

To point an embed at the dev API from a development build, add &env=dev to the URL. Leave it off in production: without it the embed talks to the production API, so existing integrations are unaffected. The live preview on the right follows the environment selected in the top bar.

About withdrawals

• Funds go out by ACH, so the destination must be a linked bank account. Cards are not offered as destinations. Users with no linked bank see a prompt to link one.
• Withdrawals complete asynchronously. The screen confirms as Pending and the money typically lands in 1–2 business days; the outcome shows up in GET /v1/users/{userId}/wallet/transactions. There is no fee.
• The headline figure is the withdrawable balance, not the wallet balance, and Max binds to it. Where the two differ — funds still processing, a pending card purchase, or promotional credit — the screen shows the wallet balance underneath with a short explanation. Build the same behavior into your own screen with GET /v1/users/{userId}/wallet/withdrawable-balance.
• Withdrawals are configured per program. Until they are, the screen says so rather than offering a withdrawal that cannot succeed — contact your account contact to have them turned on.