Skip to guide
Docs
DOCUMENTATION/API & SDK REFERENCE
REFERENCE / API & SDK

The interface, without the guesswork.

Use the bundled SDK in Chrome. Use authenticated server endpoints for web apps and protected backend features.

Base URL and credentials#

TopPay API origin
https://toppayext.com
ValueUseWhere it belongs
App ID · app_…Selects the productPublic configuration
Pricing plan ID · prf_…Selects the plan; named profileId in the APIPublic configuration
Tracking key · pf_pub_…Counts usage events for an appPublic tracking code
TopPay server API keyAuthorizes server API calls for its appYour backend’s secret manager only
Chrome identityTokenIdentifies one customer installationSDK-managed local storage; do not share or log it

“Pricing plan” in the dashboard and profileId in requests refer to the same thing. The SDK’s apiBaseUrl includes /api; raw REST calls below include the full /api/v1/… path.

Chrome SDK methods#

Initialize the local SDK
const topPay = TopPay("YOUR_TOPPAY_APP_ID", {
  profileId: "YOUR_PAYMENT_PROFILE_ID",
  apiBaseUrl: "https://toppayext.com/api"
});
MethodResult / behavior
watchAccess(listener, options)Returns an unsubscribe function. Checks access while the UI is open; calls the listener with active, status, blocked, billingAvailable, and entitlements. Supports profileId or explicit alternative profileIds.
startAnalytics()Register install/update/removal tracking and retries at background-worker top level. Requires publicKey, storage, alarms, and host access.
track(event)Report app_open or feature_* activity from your feature handlers. Requires the analytics worker.
identifyEmail(email, {consent: true})Associate an intentionally shared address with the installation; does not verify identity or grant access.
getUser({ profileId })Returns active, paid (compatibility alias), status, blocked, billingAvailable, email, and entitlements. Pass or configure the selected plan; omitting both checks any plan for the installation.
getPlans()Returns active pricing plans with id, name, kind, amount, currency, and trial_days. Amounts are integer minor currency units.
openPaymentPage({ email, profileId })Creates checkout in a compact Stripe window. With startBackground, verifies the return and reopens the popup when supported. Requires a plan; email is optional. Stripe collects it when omitted.
openBillingPortal()Opens a portal for the Stripe customer linked to the current Chrome identity, or throws an error.
startBackground()Register at worker top level for managed checkout return and periodic access checks. Separate from startAnalytics().

The SDK throws when an API request fails. Handle that exception and keep protected features locked. Payframe remains an alias of TopPay for older integrations.

Public and Chrome endpoints#

Send JSON with Content-Type: application/json for POST requests. These endpoints do not use the seller’s server key.

Method / endpointRequestResponse
GET/api/v1/public/profiles?appId=…{ app, mode, profiles }

mode is test, live, or disabled; only active plans are returned.

POST/api/v1/extension/access{ appId, identityToken, profileId }{ active, entitlements }

profileId is optional in the API; always supply it for a plan-specific gate.

POST/api/v1/extension/checkout{ appId, profileId, identityToken, email? }{ checkoutUrl }
POST/api/v1/extension/portal{ appId, identityToken }{ portalUrl }
GET/api/v1/pixel.gif?key=…&event=…&source=…Transparent GIF. Verify recording in the usage report, not from the image response.

Chrome identity tokens contain 32–160 letters, numbers, underscores, or hyphens. Let the SDK generate and retain them. Creating a new token per request loses the customer association.

Authenticated server endpoints#

Request headers · backend only
Content-Type: application/json
Authorization: Bearer YOUR_TOPPAY_SERVER_KEY
Method / endpointJSON requestResponse
POST/api/v1/server/customers{ appId, customerId, email? }{ registered: true }
POST/api/v1/server/checkout{ appId, profileId, customerId, email? }{ checkoutUrl }
POST/api/v1/server/access{ appId, profileId, customerId }{ active, entitlements }

Use a stable customerId of 1–160 characters derived from your own verified session. The key must belong to appId. There is no public server-customer portal endpoint in the current implementation.

Example access response
{
  "active": true,
  "entitlements": [{
    "profileId": "prf_example",
    "profileName": "Pro",
    "status": "active",
    "active": true
  }]
}

Errors and retries#

API errors normally return { "error": "A readable explanation" } with a non-2xx status. Network or platform failures may return a non-JSON response, so keep a fallback error message.

StatusTypical meaningNext step
400Missing or invalid request fieldsValidate the app, plan, and customer fields.
401Invalid server API keyCheck the app/key pair and Bearer header.
404Unknown app, unavailable extension plan, or missing billing customerCheck the resource and current installation identity.
409Seller or pricing configuration is not readyFinish setup and confirm plan syncing.
502 / 503Payment service or platform configuration failureInspect the error and request ID; retry deliberately once the issue is resolved.
CONTINUE BUILDINGDownloads & AI brief

Choose the right starter and hand clear instructions to your coding assistant.