Mini Apps

A Mini App is a web app you build once and run inside the Zela app — no download, no separate account. The Zela app loads your URL in a WebView and injects a small bridge (window.Zela) your frontend calls to know who the current user is, charge them (Checkout), and pay them out. Think Telegram Mini Apps or World App Mini Apps, for the Arc ecosystem.

1. List your Mini App

In your dashboard, go to Mini App and set a launch URL, an icon, and a tagline, then turn it on. That’s what makes you show up in the Zela app’s Mini Apps directory — nothing else about your account changes; you still use the same API keys as Checkout.

2. Install the SDK

npm install @zela-checkout/miniapp-sdk

Two halves, two entry points — use whichever runs where:

  • @zela-checkout/miniapp-sdk — your backend (Node). Needs your secret key. Never ships to the browser.
  • @zela-checkout/miniapp-sdk/client — your frontend, the code that actually runs inside the Zela app’s WebView. Needs your publishable key. Does nothing outside that WebView.

3. Know who’s using your Mini App

import { Zela } from "@zela-checkout/miniapp-sdk/client";

const user = await Zela.getUser();
// { zelaId: "harry.zela", arcAddress: "0x..." }

arcAddress is informational — you never touch a private key, and there’s nothing to sign on the client. zelaId is what you’ll pass to payouts.resolve() from your backend if you ever need to pay this user.

4. Charge the user (Checkout)

Zela.checkout() creates the session itself (the same public, publishable-key endpoint the embeddable widget uses) and hands it to the native host, which shows a native confirmation and sends the payment directly from the user’s own already-connected Arc wallet — no QR, no wallet-connect step, no leaving your Mini App.

import { Zela } from "@zela-checkout/miniapp-sdk/client";

try {
  const result = await Zela.checkout({
    publishableKey: "pk_live_...",
    amount: "4.99",
    metadata: { orderId: "ord_123" },
  });
  console.log(result); // { sessionId: "cs_...", status: "settled" }
} catch (err) {
  // user declined, or the transfer failed
}

This is exactly the session model described in REST API and Webhooks — the same checkout.session.completed webhook fires when it settles, whether the customer paid through a hosted page, the widget, or a Mini App.

5. Pay the user out (Payouts)

Always non-custodial. Zela never holds or signs for your funds — your own backend sends the on-chain transfer itself, from a wallet you control. Zela’s role is to tell you where to send it, then verify on-chain afterward that the transfer actually happened, for the right recipient and amount, so it can show up in the user’s activity and your own payouts dashboard.

import { ZelaMiniAppClient } from "@zela-checkout/miniapp-sdk";

const client = new ZelaMiniAppClient({ secretKey: process.env.ZELA_SECRET_KEY! });

// 1. Resolve who you're paying — a Zela ID, email, or merchant ID.
const { walletAddress } = await client.payouts.resolve("harry.zela");

// 2. Send the transfer yourself. However you already sign Arc transactions
//    (viem, ethers, your own signer) — Zela is not involved in this step.
const txHash = await sendUsdcYourself(walletAddress, "2.50");

// 3. Report it. Zela verifies the transaction on-chain before recording it.
const { payout } = await client.payouts.report({
  toIdentifier: "harry.zela",
  txHash,
  amount: "2.50",
});
console.log(payout.status); // "verified"

payouts.resolve() only accepts a Zela ID, email, or merchant ID (store.zela.merchant) — not a raw wallet address, since there’s nothing to resolve for one. Payouts don’t support sandbox keys: every payout is a real transfer on Arc mainnet, so use a production secret key.

Bridge reference

CallReturnsNotes
Zela.isAvailable()booleanTrue inside the Zela app’s Mini App host. Use it to render a fallback if your Mini App is also a plain website.
Zela.getUser(){ zelaId, arcAddress }Never includes a private key or anything sensitive.
Zela.checkout(request){ sessionId, status: "settled" }Rejects if the user declines or the transfer fails.
Zela.close()voidReturns to the Zela app’s own UI.

Mini Apps reuse everything else already documented: the same fees (see Fees), the same webhook signing (Webhooks), and the same account/dashboard you already use for Checkout.