Integrate Stripe
If you are offering your product through a website or planning to do so, integrating Stripe with Botsi allows you to manage web-based payments and subscriptions efficiently. This setup enables you to:
- Automatically activate paid features for users who purchased through your website and later sign in to the app.
- Access unified subscription analytics directly from your Botsi Dashboard, including insights like cohorts and revenue predictions.
How it fits together
Botsi and Stripe split the work into two directions. Decisions go out: your server calls the Botsi API with your secret key to create profiles and fetch AI-priced paywalls. Results come back: your Stripe account notifies Botsi of every purchase, renewal, and refund through this connection. You never call an API to report a purchase.
The customer_user_id you set in Stripe metadata ties steps 2 and 3 back to the profile from step 1.
More detail on the two directions
Decisions out (Botsi API, secret key). Your server creates a profile for each user, fetches the paywall Botsi predicts for them, and reports impressions. This is covered by the AI Pricing Web API guide and needs only your Botsi secret key.
Results back (this Stripe connection). Stripe notifies Botsi of purchases, renewals, refunds, and cancellations as they happen. Botsi matches each event to the profile that saw the paywall and credits it to the pricing prediction it came from. This powers analytics, experiment results, and AI model training, and it works for renewals and refunds that happen months later, which no checkout-time API call could report.
The thread between them. Both directions describe the same person only if the identifiers match: set customer_user_id in the Stripe Customer's metadata to the same customerUserId you use with Botsi.
What the connection is made of
The connection is not software you install on your side, and there is no Botsi listing in the Stripe App Marketplace. It is three pieces, all set up from App Settings > Stripe in your Botsi dashboard:
- A webhook endpoint in your Stripe account. Botsi generates the URL for your app and shows it ready to copy, so there is nothing to construct by hand. You create the endpoint in Stripe and point it at that URL.
- A webhook signing secret. Stripe gives you this when you create the endpoint. It proves each event really came from your Stripe account. Botsi rejects events that fail signature verification, so the connection does not work without it.
- A Stripe API key, either secret or restricted. Botsi uses it to read the subscription, customer, and invoice behind each payment event. You generate it in Stripe during the steps below.
Botsi stores a separate set of all three for Production and Sandbox, so you can run a test environment alongside your live one. Use your Stripe test mode or sandbox credentials for the Sandbox fields.
Set up the connection
Do this once per app. The whole setup is copying three values between the Botsi and Stripe dashboards.
-
Copy your Webhook URL from Botsi.
- Go to your Botsi Dashboard >
App Settings > Stripe. - Under Webhook URL, copy the Production value. Botsi has already generated it for your app.
- Copy the Sandbox value as well if you are also setting up a test environment.
- Go to your Botsi Dashboard >
-
Create the webhook endpoint in Stripe.
- In Stripe, go to Developers > Webhooks and select Add endpoint.
- Paste the Botsi Webhook URL as the endpoint URL.
- Subscribe to the events listed under Webhook events Botsi processes below. Selecting all of them is the simplest and safest option.
-
Paste the signing secret back into Botsi.
- Stripe shows a Signing secret for the endpoint you just created. It starts with
whsec_. - In Botsi, paste it into Webhook Signing secret. Match Production to your live endpoint and Sandbox to your test endpoint.
- Stripe shows a Signing secret for the endpoint you just created. It starts with
The signing secret is required. Botsi verifies the signature on every incoming event and rejects anything it cannot verify, so purchases will not sync until this field is filled in.
-
Generate a Stripe API key.
- In Stripe, go to Developers > API keys and create a secret or restricted key.
- Stripe may require identity verification (via email, Touch ID, or a security key).
Which permissions a restricted key needs
A standard secret key works with no further configuration. If you prefer a restricted key, grant Read access to Customers, Subscriptions, Invoices, Charges, PaymentIntents, and Balance transactions. Botsi reads these to resolve the subscription, customer, and amounts behind each event.
Grant Write access to Customers only if you set profile creation behavior to client_reference_id. In that mode Botsi copies the client_reference_id from the Checkout Session into the Stripe Customer metadata, so that later renewals still resolve to the same profile. With a read-only key that copy is skipped and renewals may create new profiles instead.
This API key will only be visible once. Be sure to save it securely using a password manager or other secure storage.
-
Add the API key to Botsi.
- In
App Settings > Stripe, paste it into Stripe Secret API key. - Use your live key for Production and your test key for Sandbox. These are two different keys.
- In
-
Choose your profile creation behavior.
- This decides which Stripe identifier Botsi uses to match a payment to a user. The default is
customer_user_idfrom the Stripe Customer metadata. - See Profile Creation Rules for the full options.
- This decides which Stripe identifier Botsi uses to match a payment to a user. The default is
-
Save, then add your Stripe products in Botsi.
- Botsi only tracks transactions for products configured in the dashboard. Follow Set up Stripe Products.
Once this setup is complete, Botsi will begin syncing subscription data from Stripe. This connection enables your users to access purchased features across platforms and provides your team with consolidated analytics and subscription insights in one place.
Verify the connection
To confirm the connection is live, send a test event from Stripe or make a test purchase, then check Developers > Webhooks in Stripe and open your Botsi endpoint. A 200 response means Botsi accepted the event. A 400 almost always means the signing secret in Botsi does not match the one Stripe issued for that endpoint.
Webhook events Botsi processes
These are the event types Botsi listens for. Enable all of the following on the endpoint you created in step 2. Enabling everything listed here is the simplest and safest option, and it is also the list to audit against if events are not arriving.
| Events | What they tell Botsi |
|---|---|
invoice.paid, invoice.payment_failed | Purchases, renewals, and billing issues. invoice.payment_succeeded is accepted as an alias. |
customer.subscription.created / updated / deleted / paused / resumed | Trials, cancellations, and other lifecycle changes |
checkout.session.completed | Checkout Session purchases |
payment_intent.succeeded, payment_intent.payment_failed | One-time purchases |
charge.refunded, refund.created | Refunds |
charge.dispute.created | Disputes |
customer.created / updated / deleted, invoice.created / updated / deleted | Housekeeping that keeps profiles and invoices in sync |
How Botsi matches purchases to profiles
Set customer_user_id in the Stripe Customer's metadata to the same customerUserId you use with Botsi. Botsi can also fall back to matching by the Customer's email or client_reference_id. The full rules, including how to choose your preferred identifier in App Settings, are described in Profile Creation Rules.
If you promote web subscriptions inside your mobile app, be aware that Apple only allows external payment systems for digital goods in the United States. Doing so in other regions may result in App Store rejection.