AppsPro Developer Guide

# AppsPro API — Customer Reference for AI Agents

AppsPro is a subscription-management platform built on top of Dialog Axiata BDApps.
This document covers the **customer-facing** API surface only — what a developer
integrating their app with AppsPro can call. Internal dashboard endpoints are
not included.

Base URL: https://api.appspro.dev
SDK Base URI (shown in your dashboard): https://api.appspro.dev/api/v1

---

## Credentials (issued per app in the AppsPro dashboard)

- publishable_key — client-side safe (e.g. "pk_..."). Used in WebSDK init
                    code (AppsPro('pk_...')) and as a query param on the
                    /sdk/app-info and /embed/subscribe public endpoints.
- secret_key      — server secret (e.g. "sk_..."). The Authorization
                    Bearer token for /api/v1/sdk/* calls AND the HMAC-SHA256
                    key for verifying outbound webhook signatures. Shown
                    once on regenerate.
- url_slug        — short 10-char base62 handle (e.g. "Hd3kF9aZ2x"). Used
                    in user-facing checkout URLs: appspro.dev/s/<slug>.
                    Stable across credential rotations.

You never use an "app_id" path parameter from your side. /sdk/* endpoints
identify your app via the Bearer key; checkout URLs identify it via the
url_slug; the WebSDK identifies it via the publishable_key.

---

## Auth schemes by route group

- /api/v1/sdk/{verify,subscribers,status,otp/*,subscribe,unsubscribe}
    → Bearer (Authorization: Bearer sk_<secret>)
- /api/v1/sdk/app-info, /api/v1/sdk/generate-token
    → no auth (uses publishable_key in body / query)
- /discover/* — no auth (public marketplace)
- /s/{url_slug}/* — no auth (hosted checkout, called by browser)
- /bdapps/*       — no auth (called by BDApps, not by you — configured in BDApps portal)
- /embed/*        — no auth (token from /sdk/generate-token instead)
- /public/unsubscribe/* — no auth (end-user UI flow, not for customer code)

---

## BDApps Portal Configuration

In your BDApps developer portal, paste these URLs:

  SMS MO URL:     https://api.appspro.dev/bdapps/sms
  USSD MO URL:    https://api.appspro.dev/bdapps/ussd
  Notify URL:     https://api.appspro.dev/bdapps/notify
  Report URL:     https://api.appspro.dev/bdapps/report

These URLs are identical for every customer. AppsPro routes each incoming
payload to your app via BDApps' applicationId field.

Whitelist this source IP in the BDApps portal so we can reach you:
  217.15.160.79

You can also read these values programmatically:
GET /platform/bdapps-portal-config
  Response: { sms_url, ussd_url, notify_url, whitelisted_ips }

---

## SDK (Bearer auth or public)

GET /api/v1/sdk/verify/{subscriber_id}     // Bearer
  subscriber_id must be the BDApps subscriber ID returned by /sdk/subscribers,
  e.g. "tel:8801712345678" — not the internal AppsPro UUID.
  Response: { valid: bool, subscriber?: SubscriberResponse, reason?: string }

POST /api/v1/sdk/verify/batch              // Bearer
  Body: { subscriber_ids: string[] }   // up to 500 per call
  Response: { results: [{ subscriber_id, valid, status?, reason? }] }
  // Bulk form of GET /verify/{id}, for reconcilers. Reads the local mirror
  // only — no upstream BDApps call, so it's cheap to run on a schedule.

GET /api/v1/sdk/subscribers?page=&limit=&status=
  Response: { subscribers: SubscriberResponse[], total, page, limit }

DELETE /api/v1/sdk/subscribers/by-external-id/{external_user_id}   // Bearer
  204 on success.
  // GDPR scrub: removes the phone + external_user_id from the Subscriber
  // row. Call your unsubscribe first — this does NOT cancel carrier billing.

POST /api/v1/sdk/spawn-sandbox             // Bearer (production key only)
  Response: { app_id, publishable_key, secret_key, created }
  // Creates (or re-fetches) the sandbox twin of the calling app. Idempotent:
  // a second call returns the same credentials with created=false.
  // 409 if the calling key already belongs to a sandbox app.

POST /api/v1/sdk/status                    // Bearer
  Body: { phone }   // raw "01XXXXXXXXX"
  Response: { subscription_status, status_code, status_detail, raw }
  // Queries BDApps live (not local DB) so it's truth even before notify webhook.

POST /api/v1/sdk/otp/request               // Bearer Rate limit 10/h/phone/app.
  Body: { phone, external_user_id? }
  Response: { reference_no, status_code, status_detail, raw }
  // Sends a real SMS. Pass reference_no back to /sdk/otp/verify.

POST /api/v1/sdk/otp/verify                // Bearer
  Body: { reference_no, otp, external_user_id? }
  Response: { subscription_status, subscriber_id, local_subscriber_id, status_code, status_detail, raw }
  // On success, registers the subscriber locally. It does NOT itself fire a
  // webhook: subscriber.created is emitted when BDApps posts its confirming
  // callback to /bdapps/notify, which can lag this response. Use the response
  // to unlock access; use the webhook to reconcile.

POST /api/v1/sdk/subscribe                 // Bearer
  Body: { phone, external_user_id? }
  Response: { status_code, status_detail, raw }
  // Direct subscribe without OTP. For trusted server-to-server use.

POST /api/v1/sdk/unsubscribe               // Bearer
  Body: { phone, external_user_id? }
  Response: { status_code, status_detail, raw }
  // Success if statusCode == "S1000" OR raw.subscriptionStatus == "UNREGISTERED".

external_user_id (optional, max 100 chars) is your own identifier for the
user. It is stored on the Subscriber and echoed back in webhook payloads,
so you can match deliveries without normalising phone numbers.

GET /api/v1/sdk/app-info?publishable_key=...    // no auth (legacy ?public_key= alias accepted)
  Response: {
    name, description, category, pricing_model, icon_url,
    organization,          // developer's org name, falls back to their name
    publishable_key,
    client_id,             // == url_slug; the path segment for /s/{slug}/...
    url_slug,              // same value, both names are returned
    pricing: [{ method_name, display_name, price, price_inclusive,
                billing_period }],
    payment_method_icons: [{ method_name, carrier_name, icon_url }],
    is_sandbox,            // true when this key belongs to a sandbox app
    disclosure_md,         // BDApps-required pricing disclosure line
    supported_countries    // ["BD"] — BDApps is Bangladesh-only for now
  }

POST /api/v1/sdk/generate-token             // no auth, scoped to Origin
  Body: { publishableKey }   // accepts legacy publicKey too
  Response: { token, expires_in: 300 }

SubscriberResponse:
  { id, bdapps_subscriber_id, phone_masked, status, subscription_type, frequency, subscribed_at, cancelled_at, created_at }

---

## Hosted Checkout (no auth)

User-facing page: https://appspro.dev/s/{url_slug}

GET  /s/{url_slug}/info
  Response: { name, description, icon_url, banner_url, pricing_model, category }

POST /s/{url_slug}/otp/request
  Body: { phone, external_user_id? }
  Response: { status_code, status_detail, raw, reference_no }

POST /s/{url_slug}/otp/verify
  Body: { reference_no, otp, external_user_id? }
  Response: { status_code, status_detail, raw, subscription_status, subscriber_id,
              local_subscriber_id, redirect_url, download_token, subscription_token }

Phone formats accepted: 01XXXXXXXXX, 8801XXXXXXXXX, or +8801XXXXXXXXX.

### Subscription session (client-safe status + cancel)

A successful /otp/verify also returns "subscription_token" — a 30-day JWT
bound to (app_id, subscriber_id). It authorises the two routes below, which
exist so a client that CANNOT hold the secret key (a mobile app) can still
read and cancel its own subscription. The token only ever addresses the one
subscription its holder proved via OTP, so it grants strictly less than the
secret key does. Store it; the server rotates it on every read.

GET  /s/{url_slug}/subscription        // Auth: Bearer <subscription_token>
  Query: upstream=true to force a live BDApps lookup instead of the local
         mirror (costs a TAP round-trip; the mirror is kept current by
         /bdapps/notify).
  Response: { valid, status, reason, subscribed_at, cancelled_at, subscription_token }
  Note: valid is TRUE for both "active" and "pending".
  401 -> token expired or revoked; 403 -> token belongs to a different app.

POST /s/{url_slug}/unsubscribe         // Auth: Bearer <subscription_token>
  Body: none. The phone is resolved server-side from the stored subscriber
        row, so this cannot be used to unsubscribe an arbitrary number.
  Response: { status_code, status_detail, raw }
  409 -> no phone recoverable for that subscriber.

---

## Discover / Marketplace (no auth)

Public catalogue of apps that have been published on AppsPro. Useful if
your app is listed and you want to surface its marketplace metadata, or
if you're building an external directory page.

GET /discover/apps?page=&limit=&search=&category=
  Response: { apps: DiscoverAppItem[], total, page, limit }
  Pagination: page >= 1, limit in [1, 100] (default 20).

GET /discover/apps/{url_slug}
  Response: DiscoverAppItem
  404 if the slug doesn't match a published app.

GET /discover/apps/{url_slug}/download
  302 redirect to the latest APK URL; also increments downloads_count.
  404 if the app isn't an Android app or has no published APK.

DiscoverAppItem:
  {
    name, description,
    description_html,      // sanitized HTML rendered from the Markdown description
    icon_url, banner_url, screenshots, category, pricing_model,
    url_slug,
    publishable_key,       // safe in browser code — lets you reuse /sdk/app-info
    developer_name, organization,
    downloads_count,       // NOT subscriber_count
    app_type,              // "android" | "web"
    apk_url, web_url,
    requires_subscription, // true when the APK download is gated behind a sub
    versions: [{ version_name, release_notes, created_at }],
    pricing:  [{ method_name, display_name, price, price_inclusive,
                 billing_period, carrier_label }],
    tax_rates: { ... }     // current VAT/SD/SC percentages, for a breakdown tooltip
  }

  price            — pre-tax base price as entered by the merchant
  price_inclusive  — base + VAT + SD + SC, computed for display
  carrier_label    — carrier name(s) behind the method ("Robi/Airtel"),
                     resolved server-side so an admin rename reaches you

---

## Webhooks (your server receives POSTs from AppsPro)

Configure your webhook URL and event list in the AppsPro dashboard.

Headers on every delivery:
  Content-Type:  application/json
  X-Event-Type:  <event name>
  X-Event-Id:    <UUID, stable across retries of the same delivery>
  X-Timestamp:   <unix seconds, part of the signed string>
  X-Body-Sha256: <sha256 hex of the exact bytes sent>
  X-Signature:   <hex HMAC-SHA256, NO "sha256=" prefix>

SIGNATURE — sign the RAW REQUEST BYTES, not a re-serialised parse:
  signed_string = f"{X-Timestamp}.".encode() + raw_body
  expected      = hmac.new(key, signed_string, hashlib.sha256).hexdigest()
  key           = the webhook signing_secret if set in the dashboard,
                  else the app's secret_key
Also verify sha256(raw_body) == X-Body-Sha256, and reject deliveries whose
X-Timestamp is more than 5 minutes from your clock.
Do NOT re-serialise the parsed JSON and hash that — we sign what we put on
the wire, so a parse/re-dump round trip will not reproduce the same bytes.

Event types (this is the complete set that is DELIVERED):
  subscription lifecycle (from the BDApps notify callback):
    subscriber.created       // REGISTERED, not previously cancelled
    subscriber.reactivated   // REGISTERED, was cancelled
    subscriber.cancelled     // UNREGISTERED
    subscriber.<status>      // any other status, lowercased — match the
                             // prefix so a new upstream status doesn't break you
  inbound messaging (forwarded from BDApps):
    sms.received, ussd.received
NOT delivered: checkout.otp.requested and checkout.otp.verify.failed are
written to the app's internal event log for the dashboard only. To react to
a successful hosted checkout, listen for subscriber.created — but note it is
emitted from the inbound /bdapps/notify callback, not from OTP verify, so it
lags a successful subscribe. A client polling GET /s/{url_slug}/subscription
sees "pending" during that window, which counts as subscribed.

Every event uses the same envelope; only "data" varies:
  {
    "event_id": "3f9c1e6a-...",
    "event_type": "subscriber.created",
    "occurred_at": "2026-05-11T10:30:00+00:00",
    "application_id": "550e8400-...",   // your AppsPro app id (UUID)
    "is_sandbox": false,
    "data": {
      "subscriber_id": "tel:8801712345678",
      "local_subscriber_id": "9c8b7a6d-...",
      "external_user_id": "your-user-123",
      "status": "REGISTERED",
      "frequency": "daily",
      "subscribed_at": "2026-05-11T10:30:00+00:00",
      "cancelled_at": null
    }
  }

For sms.received / ussd.received the envelope is identical and "data" is the
raw BDApps MO payload ({ applicationId, sourceAddress, message, requestId,
encoding } for SMS).

---

## Embed (no auth)

GET /embed/subscribe?publishable_key=&token=&theme=&locale=&button_text=&button_color=&compact=&hide_header=
  → HTML page suitable for iframe embedding
  token comes from POST /api/v1/sdk/generate-token
  (legacy ?public_key= query is still accepted)

---

## WebSDK (browser JS — appspro.js)

Embed a subscription widget directly in your website or mobile WebView.
The widget is injected as plain HTML into your container — no iframe, no
postMessage — so it works reliably in Android/iOS WebViews.

### Install

  <script src="https://appspro.dev/sdk/v1/appspro.js"></script>

  // Legacy URL /sdk/v1/texionapps.js is still served as a symlink to
  // appspro.js but is deprecated — use the new filename in new pages.

### Init

  const sdk = AppsPro(publicKey, { baseUrl });

- publicKey: your publishable_key (e.g. "pk_..."). Safe to ship to the browser.
- baseUrl  (required): the API host, "https://api.appspro.dev". The SDK does
  not auto-detect this — the script is served from appspro.dev but the API
  lives on api.appspro.dev, so it must be passed explicitly.

### Create the subscribe element

  const el = sdk.elements.create('subscribe', {
    buttonText:   string,    // default: 'Subscribe Now'
    buttonColor:  string,    // default: '#3b82f6' (CSS color)
    theme:        'dark' | 'light',  // default: 'light'
    borderRadius: string,    // default: '16px'
    logoUrl:      string,    // override the "Powered by AppsPro" footer mark
  });

NOTE: compact and hideHeader are NOT element options — they are
query params of the /embed/subscribe iframe (compact, hide_header) and
are ignored by elements.create(). The iframe surface uses snake_case
(button_text, button_color) and defaults to theme=dark,
button_color=#6366f1; the WebSDK element uses camelCase and defaults to
theme=light, buttonColor=#3b82f6. Don't mix the two.

### Element API

  el.mount(selector);    // selector string, e.g. '#subscribe-box'
  el.unmount();          // remove from DOM
  el.update(opts);       // change options on a mounted element
  el.on(event, cb);      // subscribe to events (see below)

mount() fetches /api/v1/sdk/app-info under the hood to render the header.

### Events

  ready             → {}                                                — widget has rendered in the DOM
  otp-sent          → { phone }                                         — OTP SMS was dispatched
  success           → { subscriberId, localSubscriberId, redirectUrl }  — user subscribed
  payment-redirect  → { url }                                           — forwarded from OTP verify
  error             → { message }                                       — anything failed in the flow

On 'success', verify server-side before granting paid access:
  GET /api/v1/sdk/verify/{subscriberId}   // Bearer sk_...

### Checkout helpers (no widget)

If you don't want to embed the widget, send the user to the hosted checkout
page at https://appspro.dev/s/<url_slug>. Requires SDK v1.5+.

  const url = await sdk.createCheckoutUrl();
  // → "https://appspro.dev/s/Hd3kF9aZ2x"

  // Returns a Promise: the url_slug comes from /sdk/app-info. Pass it
  // explicitly to skip that round trip.
  const url2 = await sdk.createCheckoutUrl({ urlSlug: 'Hd3kF9aZ2x' });

  sdk.openCheckout({ width: 460, height: 600 });
  // Opens a centered popup named 'appspro-checkout'. The window is opened
  // synchronously and navigated once the URL resolves, so popup blockers
  // don't fire.

There is no redirect option. The post-subscribe destination is the app's
checkout_redirect_url, set in the dashboard settings tab; taking one from
the caller would make /s/* an open redirect.

In v1.4 and earlier createCheckoutUrl() returned a string built as
"<baseUrl>/checkout?public_key=..." — a route that does not exist, on the
API host rather than the web host. Every URL it returned 404'd.

### Mobile WebView (legacy — prefer the native Flutter SDK below)

The SDK auto-posts every event to a JavaScript channel named "AppsPro":

  window.AppsPro.postMessage(JSON.stringify({ type, data }));

Register a channel of that exact name and parse the JSON to receive
ready/otp-sent/success/payment-redirect/error events. No extra JS wiring is
needed inside the WebView. For Flutter apps use appspro_sdk instead; keep
this for Cordova/Capacitor shells or an existing WebView you already ship.

---

## Flutter SDK (pub.dev — appspro_sdk)

Native Flutter package. Same flow as the WebSDK, no WebView. Material 3
widgets that inherit the host app's ThemeData. Supports Android, iOS, web,
macOS, Windows and Linux.

  Package: https://pub.dev/packages/appspro_sdk
  Source:  https://github.com/texion-tech/appspro-sdk-flutter

### Install

  # pubspec.yaml
  dependencies:
    appspro_sdk: ^0.1.0

### Configure (once, in main())

  import 'package:appspro_sdk/appspro_sdk.dart';

  void main() {
    AppsProClient.configure(publishableKey: 'pk_...');
    runApp(const MyApp());
  }

Only the PUBLISHABLE key goes in the app. The secret key authorises
server-to-server calls and signs webhooks — never ship it in a binary.
Optional named args: baseUrl (defaults to https://api.appspro.dev),
backend, tokenStore, statusResolver, unsubscribeHandler, externalUserId.

### Widgets

  // Full screen — the one-line integration. Returns null if dismissed.
  final result = await AppsProSubscribeScreen.show(context);
  if (result?.isSubscribed ?? false) unlockPremium();

  // Inline card, for your own paywall screen.
  AppsProSubscribeCard(
    onSuccess: (SubscriptionResult r) {},
    onError: (String message) {},
    options: const AppsProOptions(subscribeLabel: 'Start', showBranding: false),
  )

  // Button that opens the subscribe screen.
  AppsProSubscribeButton(onSuccess: (r) {})

  // Gate content behind a subscription.
  AppsProSubscriptionGate(
    builder: (context) => const PremiumScreen(),
    fallback: (context, subscribe) => Paywall(onTap: subscribe),
  )

  // Status + cancel. Both app stores expect in-app cancellation.
  await AppsProManageScreen.show(context);

### Headless client

  final client = AppsProClient.instance;
  final AppInfo info               = await client.appInfo();
  final OtpRequestResult otp       = await client.requestOtp('01712345678');
  final SubscriptionResult result  = await client.verifyOtp(otp.referenceNo!, '123456');
  final SubscriptionStatus status  = await client.subscriptionStatus();
  await client.unsubscribe();

### Custom UI — SubscribeController (ChangeNotifier)

  final controller = SubscribeController()..load();
  controller.addListener(() => setState(() {}));
  await controller.submitPhone('01712345678');
  await controller.submitOtp('123456');
  await controller.resendOtp();       // no-op during the cooldown
  controller.backToPhone();
  controller.reset();

  Reads: step, appInfo, phone, error, result, isBusy,
         resendCooldownRemaining
  SubscribeStep: loading | phone | sendingOtp | otp | verifying |
                 success | failed

There is a 120s resend cooldown by default. The server allows 10 OTPs per
hour per phone per app and each one is a real SMS, so without a cooldown an
impatient user can exhaust the hour and be unable to subscribe at all.

### Route through your own backend

Default is AppsProDirectBackend (publishable key, straight to AppsPro).
To proxy everything through your server — so it holds the secret key, ties
the subscription to your own user id, and authorises every call:

  AppsProClient.configure(
    publishableKey: 'pk_...',
    backend: AppsProProxyBackend(
      baseUrl: 'https://api.mystore.com',
      headers: () async => {'Authorization': 'Bearer ' + await session.token()},
    ),
  );

Your server implements five routes (paths configurable via
AppsProProxyPaths). They must speak the same JSON as AppsPro:

  GET  /appspro/app-info       -> the /api/v1/sdk/app-info payload
  POST /appspro/otp/request    <- { phone, external_user_id? }
  POST /appspro/otp/verify     <- { reference_no, otp, external_user_id? }
  GET  /appspro/subscription   -> { valid, status, reason? }
  POST /appspro/unsubscribe    -> any 2xx

A proxying merchant needs NONE of the subscription-token routes: their own
session is the credential, and their server can use the richer Bearer routes
(/api/v1/sdk/verify/{id}, /status, /unsubscribe).

To override only one call and leave the rest direct:

  AppsProClient.configure(
    publishableKey: 'pk_...',
    statusResolver: () async => mySubscriptionStatus(),
  );

### Errors — all subclass AppsProException (read .message)

  AppsProNetworkException        // never reached the server; retry
  AppsProInvalidPhoneException   // not a valid BD mobile
  AppsProInvalidOtpException     // wrong/expired code
  AppsProRateLimitException      // 10 OTPs/hour exhausted
  AppsProUnauthorizedException   // no valid session; subscribe again
  AppsProNotConfiguredException  // app has no BDApps credentials
  AppsProUnknownAppException     // publishable key matches no app

### Testing

Sandbox keys (API & SDK tab -> Sandbox Keys) hit a mock carrier: no SMS, no
charges, OTP is always 000000. The sandbox app and its keys are deleted when
the app is published, so release builds must use the production key.

  flutter run --dart-define=APPSPRO_PUBLISHABLE_KEY=pk_sandbox_key

In your own tests, implement AppsProBackend — no HTTP needed:

  AppsProClient.configure(publishableKey: 'pk_test', backend: MyFakeBackend());

### Behaviour worth knowing

- Access is a SERVER decision. Verify entitlement on your own server before
  handing out anything valuable; a determined user controls their device.
- status "pending" counts as subscribed. The carrier's confirming callback
  lags OTP verify, and locking a paying user out in that window is worse.
- The subscription token is rotated on every status read, so an app opened
  at least monthly never has to re-run the OTP flow.
- Phone input accepts 01XXXXXXXXX, 8801XXXXXXXXX, +8801XXXXXXXXX and is
  validated on-device before any request.

---

## Inbound BDApps webhooks (no auth, called by BDApps — NOT by you)

POST /bdapps/sms      // SMS MO callback
POST /bdapps/ussd     // USSD MO callback
POST /bdapps/notify   // subscription notify
POST /bdapps/report   // SMS delivery report

You configure these URLs in the BDApps portal. Do not call them from your code.

---

## Public cross-app unsubscribe (end-user UI)

For end users who want to opt out across every app on the platform from
a single page, AppsPro hosts a public OTP-gated unsubscribe flow:

  https://appspro.dev/unsubscribe

Backend routes (POST /public/unsubscribe/otp/request, /otp/verify, and
/public/unsubscribe) are driven by that UI and are not intended to be
called from customer code. From your own code, use:

  POST /api/v1/sdk/unsubscribe    // Bearer sk_...

---

## Notes

- Phone numbers: 01XXXXXXXXX, 8801XXXXXXXXX, or +8801XXXXXXXXX (Robi/Airtel for BDApps).
- /api/v1/sdk/verify accepts the BDApps subscriber_id from /sdk/subscribers (e.g. tel:8801...).
- secret_key is shown only once when regenerating — store it immediately.
- For browser-side subscription UI, prefer the WebSDK (appspro.js) over
  the /embed/subscribe iframe — it works inside Android/iOS WebViews where
  iframes routinely break.
- Sending SMS or charging subscribers from your own backend is not part of the
  public API. Use the AppsPro dashboard for those operations.