Keep your login. Add paid access.
Your backend identifies the customer, creates checkout, and verifies access before running protected work.
Set up the server connection#
- 1
Create your app and pricing plan
Choose Web app in TopPay. Complete Stripe onboarding and create an active plan. Open Setup for the public app ID, selected plan, and integration code.
- 2
Save the server key once
Store your app’s server API key as
TOPPAY_API_KEYin your server’s secret manager. TopPay stores its hash and cannot show the original again. Replacing the key invalidates the previous key; update your backend when you rotate it. - 3
Use your verified customer identity
Take
customerIdfrom your authenticated server session. Keep that ID stable across devices. Never accept a customer ID supplied by an untrusted browser as proof of identity.
Add customers before they purchase#
After signup or login, call this from your trusted backend with the user from your verified session. No pricing plan or purchase is needed. It creates or updates the app’s customer record; it does not grant access. The owner can then manage the customer in Customers & access.
const response = await fetch("https://toppayext.com/api/v1/server/customers", {
method: "POST",
headers: {"Content-Type": "application/json",
Authorization: "Bearer " + process.env.TOPPAY_API_KEY},
body: JSON.stringify({appId: "YOUR_APP_ID",
customerId: signedInUser.id, email: signedInUser.email})
});
if (!response.ok) throw new Error("Customer registration failed");For frontend usage counts, copy the app-specific public snippet from Setup → Connect usage tracking. Web pixels count actions, not individual users, retention, or extension installs. Customer registration and aggregate tracking remain separate.
Create checkout and check access#
// Server-only module. Never bundle this into your frontend.
const ORIGIN = "https://toppayext.com";
const APP_ID = "YOUR_TOPPAY_APP_ID";
const PLAN_ID = "YOUR_PAYMENT_PROFILE_ID";
async function topPayPost(path, body) {
const response = await fetch(ORIGIN + path, {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: "Bearer " + process.env.TOPPAY_API_KEY
},
body: JSON.stringify(body)
});
const data = await response.json();
if (!response.ok) throw new Error(data.error || "TopPay request failed");
return data;
}
// signedInUser must come from YOUR verified server session.
export async function createCheckout(signedInUser) {
if (!signedInUser?.id) throw new Error("Sign in first");
return topPayPost("/api/v1/server/checkout", {
appId: APP_ID, profileId: PLAN_ID,
customerId: signedInUser.id, email: signedInUser.email
}); // Redirect the customer to the returned checkoutUrl.
}
export async function canUsePremium(signedInUser) {
if (!signedInUser?.id) return false;
try {
const result = await topPayPost("/api/v1/server/access", {
appId: APP_ID, profileId: PLAN_ID,
customerId: signedInUser.id
});
return result.active === true;
} catch {
return false; // Do not run the protected action.
}
}Call createCheckout only when the buyer requests checkout. Redirect them to the returned URL. Before each paid server action, call canUsePremium and stop if it returns false.
Handle the return from checkout#
TopPay hosts the checkout success and cancellation pages. A return URL is not a receipt or access token. When the customer returns to your app, request their current access using the same authenticated customer ID and plan. The optional web starter rechecks while open, on focus, and on reconnect; every protected backend action must still verify access.
Payment-event processing can arrive after the redirect. Show a clear pending state and a retry button instead of unlocking optimistically or repeatedly opening checkout.
Provide a route for billing help#
The current SDK billing-portal helper is for customers identified by the Chrome installation token. There is no equivalent public server-customer portal endpoint yet. Give web customers a visible seller support route for cancellation and billing help, and manage those requests through your connected Stripe account.
Methods, endpoints, request fields, responses, and key types.
