​
What it is

In this mode:
  • Each paywall has its own virtual wallet.
  • End-users top up credits directly to the developer’s paywall using Stripe Checkout.
  • Funds go directly into the developer’s Stripe account.
  • Paywalls.ai keeps a ledger of balances and charges per user within that paywall.

​
Key Differences vs Default Mode

FeatureDefault (Paywalls.ai Wallet)Stripe Payments Mode (Scoped Wallets)
Balance scopeCross-paywall (user can spend across apps)Paywall-scoped (credits usable only in the app they topped up)
Fund custodyPaywalls.ai-managedGoes directly to developer’s Stripe account
User authorizationUser must connect & approve chargesTop-up = implicit authorization
Top-up optionsCrypto, Stripe, Paywalls.ai paymentsStripe Checkout (cards, wallets, etc.)
UIPaywalls.ai wallet UIMinimal — developer can build own UI or embed Stripe
Ecosystem effectShared balance across appsSelf-contained per app credits

​
Setup

Enabling Stripe mode is simple:
  1. In your Paywall configuration, select Stripe as your payment option.
  2. Paste your Stripe Restricted API Key.
That’s it — Paywalls.ai automatically:
  • Creates the required Stripe webhook for top-up confirmations.
  • Connects your paywall to your Stripe account.
  • Starts issuing Stripe Checkout links to users when they need to top up.
No extra manual webhook setup or configuration is needed.

​
How it works

1

Top-up

  • When a user runs out of balance, Paywalls.ai returns a Stripe Checkout link.
  • User completes payment (card, Apple Pay, Google Pay, etc.).
  • Funds go directly into your Stripe account.
2

Ledger entry

  • Paywalls.ai records the payment in the paywall-scoped ledger for that user.
  • Example: user_123 → 5.00 credits in paywall_abc.
3

Spending

  • On each request, Paywalls.ai deducts from the user’s paywall balance.
  • If insufficient, another top-up link is returned.

​
When to use

✅ You want funds deposited directly in Stripe.
✅ You don’t need balances to transfer across apps.
✅ You prefer minimal UX — top-up = charge authorization.
✅ You want to keep Stripe as your single source of truth for payments. Use the default Paywalls.ai wallet if you want cross-app balances, crypto support, or ecosystem effects.

​
Notes

  • Each paywall has its own balance; credits are not portable across apps.
  • Refunds must be issued from your Stripe dashboard (Paywalls.ai will sync the ledger entry).
  • Supported currencies and payment methods depend on your Stripe configuration.
  • ⚠️ Compatibility: Stripe mode can only be enabled for paywalls with no prior activity. If a paywall already has transactions in the default mode, you cannot switch it to Stripe; you’ll need to create a new paywall instead.

​
API Keys

Paywalls.ai requires a Restricted Stripe API Key, not a full secret key.
This is safer by design, since the key is only permitted to:
  • Create a webhook (for receiving top-up events)
  • Create Checkout links (for user payments)
  • Subscribe to checkout.session.completed events
We never use the key to read customer data, process refunds, or access unrelated resources in your Stripe account.
Learn how to create Stripe API Key

​
Safety practices

  • Always use restricted keys with minimal permissions.
  • Rotate keys periodically in the Stripe dashboard.
  • Revoke old keys immediately if leaked or unused.