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#
https://toppayext.com| Value | Use | Where it belongs |
|---|---|---|
| App ID · app_… | Selects the product | Public configuration |
| Pricing plan ID · prf_… | Selects the plan; named profileId in the API | Public configuration |
| Tracking key · pf_pub_… | Counts usage events for an app | Public tracking code |
| TopPay server API key | Authorizes server API calls for its app | Your backend’s secret manager only |
| Chrome identityToken | Identifies one customer installation | SDK-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#
const topPay = TopPay("YOUR_TOPPAY_APP_ID", {
profileId: "YOUR_PAYMENT_PROFILE_ID",
apiBaseUrl: "https://toppayext.com/api"
});| Method | Result / 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 / endpoint | Request | Response |
|---|---|---|
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#
Content-Type: application/json
Authorization: Bearer YOUR_TOPPAY_SERVER_KEY| Method / endpoint | JSON request | Response |
|---|---|---|
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.
{
"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.
| Status | Typical meaning | Next step |
|---|---|---|
| 400 | Missing or invalid request fields | Validate the app, plan, and customer fields. |
| 401 | Invalid server API key | Check the app/key pair and Bearer header. |
| 404 | Unknown app, unavailable extension plan, or missing billing customer | Check the resource and current installation identity. |
| 409 | Seller or pricing configuration is not ready | Finish setup and confirm plan syncing. |
| 502 / 503 | Payment service or platform configuration failure | Inspect the error and request ID; retry deliberately once the issue is resolved. |
Choose the right starter and hand clear instructions to your coding assistant.
