Skip to guide
Docs
DOCUMENTATION/CRYPTO PAYMENTS
BUILD / CRYPTO PAYMENTS

Your wallet. Your revenue.

Optional self-custody USDC payments on Base. Developers receive 95%, TopPay receives 5%, and verified payment unlocks access.

Connect once, use across your apps#

Each card in My apps has a payment-system selector: Automatic, Stripe, or Crypto. Automatic chooses an active Stripe connection first, otherwise a saved crypto receiving wallet. Your explicit choice is saved per app. In Setup & code, the selected integration opens first and both Stripe and crypto examples remain available. This choice updates your generated code; ship that code in your app to change its purchase flow.

Open Crypto · Self-custody in the workspace sidebar and select your app. Save a public Base receiving address that you control, then enable crypto on the USD-priced plans you want to offer. The wallet belongs to your TopPay owner account and applies to all your apps. Changing it affects new checkouts; already-created checkouts keep their original recipients.

USD plan prices are charged as the same numerical amount in USDC, not converted using a live exchange rate. Non-USD plans cannot accept crypto in this release. Stripe connectivity is not required for the direct crypto SDK/API flow.

How TopPay gets its 5%#

20 USDC purchaseAmount received
Developer’s wallet19 USDC
TopPay’s wallet1 USDC

The buyer approves one payment transaction. DePay’s open-source payment route distributes both shares on-chain, with a 0% protocol-fee configuration. Network gas is separate and paid by the buyer in ETH on Base. Neither TopPay nor the developer needs to transfer the platform fee afterward.

The server checks the canonical native USDC contract, Base network, finalized successful transaction, payer identity, payment window, and net transfers to both configured receiving wallets. A browser success callback, a screenshot, or sending only the developer’s share cannot grant access. Each transaction can fulfill only one TopPay order.

Receiving your share does not require a separate TopPay payout. Sending or exchanging it later can have network or exchange fees. TopPay’s infrastructure has its own operating costs.

Lifetime purchases and manual renewals#

PlanCrypto access
One-timeLifetime
Weekly7 days · renew manually
Monthly30 days · renew manually
Yearly365 days · renew manually

There are no automatic recurring wallet deductions in this release. Renewal adds time to the existing crypto expiry, or starts from confirmation if access has expired. A duplicate verification never adds time twice. Stripe trials do not apply to crypto checkout. Owners can grant TopPay free-access trials separately.

Existing getUser(), watchAccess(), and server access checks recognize crypto purchases. Owner blocks override paid access. At expiry, premium features lock on the next check. A separate valid Stripe purchase or owner grant can still provide access. Stripe cancellation does not revoke independently purchased crypto access.

Add the optional crypto button#

Use the latest local SDK from Downloads or the configured tracking kit. Templates are optional. Newly generated Chrome starters and extension themes show a crypto button when their plan is enabled and platform setup is complete. Existing installed extensions must ship an update.

Your own extension interface
const option = await topPay.getCryptoPaymentOption({ profileId });
cryptoButton.hidden = !option.enabled;
cryptoButton.onclick = () => topPay.openCryptoPaymentPage({ profileId });
// Keep watchAccess() and getUser() before protected actions.
// To deliberately create a new checkout rather than reopen one:
// topPay.openCryptoPaymentPage({ profileId, newCheckout: true });

Crypto checkout opens in a normal TopPay browser tab for wallet compatibility. It is not a card form embedded inside the extension. The customer connects a personal EVM wallet, signs an order-specific message, then approves a native USDC payment on Base. Smart-account and exchange-transfer checkout are not supported in this first version. Reopen the extension after confirmation; its existing access checker refreshes automatically.

The SDK reopens the same checkout for up to one hour to reduce accidental duplicate payments. The checkout reference uses a URL fragment and does not contain the extension’s identity token. Treat the entire checkout URL as private.

Use crypto in your web app#

Trusted backend only
const response = await fetch('https://toppayext.com/api/v1/crypto/checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', Authorization: 'Bearer YOUR_SERVER_KEY' },
  body: JSON.stringify({ appId: APP_ID, profileId: PLAN_ID, customerId: signedInUser.id })
});
const result = await response.json();
if (!response.ok) throw new Error(result.error);
// Send result.checkoutUrl to this signed-in customer’s browser.

Derive customerId from your authenticated session, never from a browser-supplied identity. Validate the selected plan on your backend. Existing /api/v1/server/access checks recognize the purchase. Keep server keys off the browser. Add your own crypto button to a web template using this endpoint; the generated Stripe route is unchanged.

Confirmation, recovery, and support#

We wait for Base’s finalized block before unlocking. This can take around 20 minutes and can take longer during network issues. A mined wallet transaction does not mean TopPay has finished verification. Once the transaction hash reaches TopPay, a persistent verification queue continues checking while checkout is closed. The scheduled worker runs hourly, processing up to ten orders per pass; queue load can add delay. The visible checkout also polls every 15 seconds. Closing checkout can add up to an hour before the next background attempt, or longer if the queue is busy. Background retries continue for up to seven days; reopen checkout to retry afterward. Payment must be included during the one-hour checkout window, but a qualifying payment can be verified afterward.

If the browser loses the payment callback, choose Already paid? Recover your payment and paste the payment transaction hash from the signed wallet. Do not submit an approval-transaction hash. Keep the checkout URL until confirmation. If checkout closes before the transaction hash reaches TopPay, the payment cannot be discovered automatically; recovery requires the original checkout URL and transaction hash.

Verified payments appear in Customers → Payment history, workspace payment analytics (USDC separately), and Crypto · Self-custody → Verified crypto sales. The crypto sales table shows each share and its Base transaction link. Never count a frontend event as a sale.

Crypto refunds are not automatic and are not performed through Stripe’s billing portal. Contact the developer. A refund transfer does not itself revoke TopPay access; the owner must manage access separately. This release does not provide an automatic refund/split-reversal flow.

Platform activation#

The TopPay operator configures TOPPAY_CRYPTO_FEE_WALLET (public Base address), BASE_RPC_URL (HTTPS Base mainnet RPC with finalized-block support), and TOPPAY_CRYPTO_ENABLED=true through hosted environment settings. No private wallet keys are needed. Keep RPC credentials server-side. Missing configuration disables new checkout creation without affecting Stripe.

Setup provides an owner-only real-payment test even while public crypto is disabled. It uses a separate test customer and the selected plan’s real price; approve payment from a wallet different from the receiving wallets. Before enabling public payments, verify the complete wallet flow, both wallet receipts, recovery, and access on Base. Automated tests cover verification and access logic; they do not substitute for an actual wallet payment. The receiving wallet must be supplied by the platform owner, never inferred or replaced with an example address.

CONTINUE BUILDINGBilling & access

Understand subscriptions, trials, promo codes, cancellations, refunds, and customer access.