Stripe payments
Your Berrybell app can take payments with Stripe — one-off purchases, subscriptions, or checkout for a storefront. You start in a test store, and money only ever moves through your own Stripe account.
Start with a one-click test store
You don't need a Stripe account to begin. Choose Enable Stripe payments on the card the AI shows you in the chat — or Create test account under Cloud → Payments in project settings — and Berrybell creates a fully-enabled Stripe sandbox account for the project in seconds. No signup, no identity form.
On a project with environments, Cloud → Payments creates and connects accounts, and changes the Stripe mode, only while production is selected in the top bar.
From there you can build and try the whole flow with Stripe's test card numbers: checkout, the success page, receipts, and everything that happens after payment.
What Berrybell wires up for you
- Store keys, delivered for you. The store's publishable key and endpoint
reach your app as
VITE_BERRYBELL_STORE_KEYandVITE_BERRYBELL_STORE_URL, and its server also gets a store admin token and a webhook secret. Nothing is hardcoded and nothing has to be pasted by hand. These values aren't listed on the Variables page. - A domain allowlist. You choose which sites may call the store's checkout endpoint. Until you add one, any site can.
- No cut. Payments go to your own connected Stripe account and Berrybell adds no application fee on top. Stripe's own processing fees still apply.
The Payments page
Each project has a Payments page under Cloud in its project settings. It follows the environment selected in the top bar. With production selected — or on a project with only production — it has these sections:
- Stripe mode — Stripe Sandbox or Stripe Live: whether production takes test payments or real ones. This isn't the environment picked in the top bar.
- Connected accounts — a Sandbox account and a Live account, kept separate. A connected account shows whether Stripe reports Charges, Payouts and Details (account details) as enabled. Stripe keeps these up to date, and Refresh status checks again on demand; Disconnect unlinks the account from the project. An empty slot offers Create test account (sandbox, created instantly) or Create Stripe account (live, which opens Stripe's onboarding), plus Connect existing Stripe where it's offered.
- Storefront — the Publishable key and Endpoint your deployed app
uses, and Allowed origins, a comma-separated list of full origins (scheme
and host, for example
https://shop.example.com) allowed to call checkout. Each entry must match exactly, sohttps://www.example.comandhttps://example.comare separate entries. Entries that don't start withhttp://orhttps://are dropped when you save; if none are left, the list is blank. Left blank, any site can call it — in production too, although the field's hint says "blank = allow any in dev". - Test checkout — add a product with a name and price, then choose Open checkout → to pay for it on Stripe's hosted checkout page.
- Recent events — the latest payment events: checkouts completed, orders paid, subscriptions created and renewed, refunds. With production selected it covers the whole project, including test orders from the preview and your environments.
On production, Test checkout runs in the current Stripe mode. In Stripe Live it's a real checkout: paying it charges a real card, and adding a product also creates that product in your live Stripe account. The hint to use Stripe's 4242 test card appears only in sandbox.
With an environment you created selected, the page is different — see Only production takes real payments.
Building a payment flow
Describe what you want to sell in the chat:
- "Add a Buy now button for a $29 product and show a thank-you page after payment."
- "Charge $19/month for the Pro plan and unlock the dashboard for subscribers."
- "Add a checkout to the storefront for the items in the cart."
Berrybell builds the checkout and connects it to your store. The AI can create the products and prices themselves too — "add a Pro plan at $20/month" — through a permission-gated tool you approve, the same way as any other integration action. The Stripe entry in Integrations has four operations you can set permissions for: Create product, Batch create products, Create price and Check go-live status.
If production's store is in sandbox and has no sandbox account yet, the first time the AI creates a product it sets up the sandbox test account as well. Approving that call — or having set the action to Always allow — is your confirmation. That's the only account the AI can create. It can't connect an existing Stripe account, create a live one, or switch the store to live; those stay with you. With an environment you created selected, it never creates an account: its products go into the project's sandbox account, and if there isn't one, it tells you to set one up on production.
On production, the AI's products and prices go into the catalog of the current Stripe mode. While production is in Stripe Live they're created in your live Stripe account, and the preview and your environments, which always use sandbox, can't sell them.
On a project with environments, the AI's payment changes to production always show an approval card, even when the action is set to Always allow. Never allow still blocks them, and Check go-live status is a read, so it follows its permission as usual. See Production asks first.
Fulfillment — doing something after payment
Often you want something to happen after a successful payment — grant access, send a confirmation, or mark an order as paid. Ask for it directly: "when a customer pays, mark their order as paid and email them a receipt."
The after-payment event is delivered to a route in your app — the copy of it that took the order:
- Production's orders go to its published production address, so after-payment logic only works there once the project is published to production.
- An environment's orders go to that environment's latest live deployment, not to production's. If it has none, nothing is sent. One exception: a refund of a subscription payment made in an environment can't be traced back to it and is sent to production's app.
- Checkouts in the preview go to the newest automatic preview deploy, and nowhere if there isn't one. The exception: when that deploy runs on production's data while the store is in Stripe Live, the order isn't sent at all, so a test order can't land in your live data.
So while the store is in sandbox and the preview runs on production's data — always the case on a project with only production — test orders placed in the preview are fulfilled against production's data.
An environment published before it had its own webhook secret receives nothing, and orders placed before you publish it again are never delivered. Delivery also stops if the address stops resolving, for example a custom domain that has been paused. Each delivery is tried up to three times, with 8 seconds allowed for each attempt, and isn't replayed later, though the event stays recorded.
Going live
A sandbox store stays in the sandbox until you deliberately move it. In Cloud → Payments, under Stripe mode, Stripe Live stays disabled until:
- a separate live Stripe account is connected to the project, and
- Stripe reports the account's Charges, Payouts and Details as all enabled.
Switching needs the Editor role, and on a project with environments the page offers it only while production is selected in the top bar. Berrybell checks the live account with Stripe again at the moment you switch, and refuses if it's no longer fully enabled: "Stripe account must have charges, payouts and details enabled before going live". Choosing Stripe Live on the page switches straight away, with no further confirmation.
Going live also depends on the Berrybell server having live Stripe keys configured; the page tells you when it doesn't. When you make the switch from the chat card, Berrybell asks you to confirm in as many words that real cards will be charged.
Before you switch:
- The full flow works end-to-end in the sandbox.
- Success and failure states both behave correctly.
- The project is published to production, and after-payment actions (access, emails, order status) fire as expected.
Then switch and do one small real transaction to confirm.
Test with Stripe's test card numbers while you're in the sandbox. Only go live once the full flow behaves the way you want.
Only production takes real payments
The Stripe mode applies to production only. The Studio's live preview, the automatic preview deploys and every environment you create always use Stripe sandbox, on the project's one sandbox account — even while production is in Stripe Live.
- They share one test catalog. A product created by the preview's or an environment's app, by the AI while an environment is selected, or on an environment's Payments page appears in all of them, and on production while it's in sandbox. Products created on production while it's in Stripe Live, whether by the AI or with Test checkout, go into the live catalog instead.
- No sandbox account means no checkout. Without a sandbox account, checkout there fails. It never falls back to live.
- Each environment gets its own store keys. An environment you create receives its own store key, admin token and webhook secret when you publish it. Until then, its checkout is off, and Cloud → Payments says "This environment's app has no store key yet, so checkout in the deployed app is off. It gets its own key the next time this environment is published." An environment published before it had its own key keeps using the project's until you publish it again. While it does, only checkouts started in the browser on the environment's Berrybell address are forced to sandbox. A checkout its server starts runs in production's Stripe mode, and its after-payment event goes to production's app. Cloud → Payments also shows the no-store-key message for it, even though its checkout still works. Publish each environment again before you switch production to Stripe Live.
- Live Stripe keys you store yourself are withheld from the preview, the agent sandbox and your environments. See Live Stripe keys reach production only.
With an environment you created selected in the top bar, Cloud → Payments says that it always uses the project's sandbox account, with a Switch environment button that opens the top bar's environment menu. Below that are its products, a Test checkout that runs in sandbox, and its own Recent events. If the project has no sandbox account, the page says so and points you to production. There are no Stripe mode, account or storefront controls — select production to change those.
Allowed origins are set on production and cover your environments too. When the list isn't blank, each environment's Berrybell address is allowed automatically for that environment's own key, but a custom domain on an environment has to be added to the list by hand. When the list is blank, any site can call checkout in every environment.
Refunds
There's no refund button in the Studio today — issue refunds from your Stripe Dashboard.
Next steps
- Store orders and customers: Databases
- Try payment changes on a copy first: Environments
- Review integration permissions: Integrations overview