App Distribution & Lifecycle

BitCommerz apps are externally hosted: you run your own web service, and the platform integrates it via OAuth, an embedded iframe, and webhooks. This page describes the end-to-end publishing lifecycle.

ui_slots code-injection widgets (rendering into storefront/dashboard slots) are phase-2 — you may declare them in your submission, but nothing renders them yet.

Lifecycle at a glance

1. Create        You create an app in the Partner Panel (Apps -> Create App)
   |
2. Submit        Saving submits it for review (status: pending)
   |
3. Review        A BitCommerz super-admin reviews the submission
   |
4. Approve       status -> published. On approval the platform:
                   - issues your OAuth client_id + client_secret
                   - syncs the app into the merchant App Store catalog
   |
5. Install       Merchants install it from their dashboard App Store
                 (free -> instant; paid -> checkout first)
   |
6. Run           Your app is embedded via iframe / redirect and receives
                 the webhooks it subscribed to

1-2. Create & submit (Partner Panel)

Apps -> Create App. Provide the fields described in App Configuration and Listing Content. Saving the form submits the app for review (status: pending). Editing a submitted app and saving resubmits it (same app, back to pending) — resubmission is a version update, not a new app.

3-4. Review & approval

A super-admin approves (published) or rejects (rejected) your submission. Validation is enforced at submit time:

  • every URL (App URL / Redirect / Webhooks) must be https and must not resolve to a private/internal address;
  • events_subscribed and permissions must be from the published allowlists (unknown values are rejected).

On approval the platform issues your OAuth client_id and client_secret. The secret is shown once in the Partner Panel app-detail page — copy it immediately; only a hash is stored server-side. The app is then synced into the merchant App Store catalog and becomes installable.

5. Distribution & install

Once published, merchants find your app in their dashboard App Store:

  • Free apps install instantly.
  • Paid apps require checkout; access is granted by an entitlement, never by raw payment state.

Uninstalling emits app.uninstalled so your service can clean up.

6. Runtime

Your app is opened embedded in a sandboxed iframe, loaded from your Redirect URL. The dashboard appends code, api and shop_id to that URL — code is a one-time launch code, not an access token. Your server exchanges it for an access token and uses that to read the shop's data from the Merchant API — see Building Your App (Runtime & Data). Your app also receives HMAC-signed webhooks for the events it subscribed to (see App Configuration -> Webhooks).

Phase-2 (planned, not yet available)

  • ui_slots storefront/dashboard widget rendering
  • GDPR compliance webhooks (shop/customer data erasure)
  • custom / unlisted distribution (private install links)