Skip to guide
Docs
DOCUMENTATION/BILLING & ACCESS
OPERATE / BILLING & ACCESS

Understand what unlocks premium.

Your app asks for access. TopPay combines verified billing, owner grants, and customer blocks to answer.

Manage your customer database#

Open My apps → your app → Customers & access → Manage. Search emails or IDs, inspect billing status and recorded payment events, and change access. Tracked extension installations appear before payment. Web customers appear after backend registration or checkout creation. Records are isolated by app owner; identities are not merged by matching email.

Owner actionEffect
Block all accessDenies every plan and prevents new checkout attempts for this identity. A later Stripe webhook cannot remove this block.
Restore normal accessRemoves the block. Existing valid purchases or grants decide access.
Grant complimentary accessUnlocks one plan for a chosen duration or without expiry. Creates no sale.
Start / restart free trialStarts TopPay free access from now and replaces the previous manual grant for that plan.
Extend free trialAdds days to an existing TopPay free trial; expired trials extend from now.
Remove manual accessReturns the plan to billing-managed access. Valid purchases still work.

Changes take effect on the next SDK/API access check. They cannot remotely uninstall Chrome extensions or sign users out of your app. Check before every protected action and enforce server-hosted work on your backend. Offline or permanently cached access cannot receive these changes.

Each owner action has a timestamp and optional note. Customer payment history records signed events from this release onward; historical charges are not backfilled. The billing panel still shows existing subscriptions and purchases. Stripe stores card data; TopPay stores identifiers and payment results.

Follow the payment lifecycle#

  1. 1

    Your customer chooses a plan

    The app starts checkout for the selected app, pricing plan, and customer identity.

  2. 2

    Stripe processes checkout

    The customer pays or starts an eligible trial. Opening or cancelling checkout does not grant access.

  3. 3

    TopPay processes the signed event

    Stripe events update the customer’s entitlement. The checkout redirect can arrive before that update.

  4. 4

    Your app checks access

    Use active === true for the selected plan before unlocking a feature. Repeat the check for later paid actions.

Billing access rules (unless the owner overrides access)#

SituationCurrent TopPay behavior
Active or trialing entitlementAccess is allowed while its paid/trial period is valid. An active entitlement without an end date is allowed.
Checkout opened or cancelledNo new access is granted merely from starting or leaving checkout.
Cancellation scheduled for period endAccess can continue while the subscription remains active and its period has not expired.
Past due, cancelled, or expired entitlementAccess is denied by the access check.
Full refundThe related access is revoked when the full-refund event is processed.
Partial refundIt does not automatically revoke access under the current full-refund rule.
Open disputeThe related entitlement is blocked when the dispute event is processed.
Network or API failureYour integration should keep protected actions locked and offer retry.

An owner block takes precedence over all access. A valid complimentary or free-trial grant can provide access even if billing access has expired or been revoked. Use the API’s access result rather than inferring status from a receipt, a local flag, or your own countdown. Check each pricing plan separately.

Let extension customers manage billing#

The bundled SDK exposes a billing-portal helper for the current Chrome identity. Offer it after a Stripe customer has been linked to that installation.

Open billing management
try {
  await topPay.openBillingPortal();
} catch (error) {
  showBillingHelp(error.message); // Your product’s support UI.
}

The portal’s available actions depend on the connected seller’s Stripe configuration. If no billing customer is linked, TopPay returns an error. Always provide a seller contact route if billing management is unavailable.

Offer subscription promotion codes#

Open My apps → your app → Pricing and create the code in TopPay’s Seller promotions section. TopPay creates the coupon and promotion code in the seller’s connected Stripe account, restricts it to this app’s subscription product, and automatically enables Stripe’s promotion-code entry for future Checkout sessions.

  1. 1

    Create the code in TopPay

    Choose a short code, discount, duration, redemption limit, and optional expiry. Use First payment only for an introductory offer; use Every renewal only when you intend the discount to continue.

  2. 2

    Start a new Checkout session

    Close any Checkout page that was already open, then use your extension or web app’s purchase button again. Stripe reads the promotion-code setting only when a new Checkout Session is created. The fresh page displays an Add promotion code link.

  3. 3

    Enter and test the code

    Enter the code on Stripe Checkout and confirm the total changes before completing a live payment. A discounted subscription follows the same refund and cancellation lifecycle as the subscription itself.

Never share a promotion code until you have tested it in the same Stripe mode—live or test—that your customers will use.

Separate seller setup from customer accounts#

Your TopPay login is the seller workspace. It does not sign customers into your product. Stripe seller onboarding enables you to accept payments; it does not provide purchase restoration for Chrome users.

Understand the platform fee#

TopPay’s application fee is 5% of a successful payment, with no monthly TopPay platform fee. Stripe fees are separate. Checkout uses the connected seller account; TopPay is not a Merchant of Record. The dashboard’s gross payment totals are before fees, refunds, and disputes.

CONTINUE BUILDINGTest your integration

Know what to test and what success looks like before launch.