Stripe is the only fully-implemented PSP in BetterSuite today. Connecting it lets your tenant accept card payments and, through Stripe Connect Express, pay your drivers, vendors, and service providers. The other PSPs that show up in the dropdown (MercadoPago, Razorpay, etc.) are present as backend entries but are not wired end-to-end yet — only Stripe supports the full charge / refund / webhook / payout path.
Before you start
- A Stripe account in good standing. Sign up at stripe.com and finish their business verification first — most setup blockers come from a half-verified account, not from BetterSuite.
- A Stripe secret API key and, optionally, your publishable key. You'll paste these into the Ops Console.
- A region row already configured under
Management Common → Regions. Each PSP account is scoped to one or more regions, so the regions need to exist before you link them.
If Stripe doesn't operate where you do, the other PSP entries in the provider dropdown are placeholders — they don't yet take real charges. Tell us which provider you need; the plugin scaffolding is there, the integration work is the gap.
Step 1: Add the PSP account
In Ops Console → Management Common → PSP Accounts, click Add. The form opens with three sections:
Provider settings
- Provider — pick
Stripe. The dropdown also lists PayPal, Razorpay, Flutterwave, Adyen, Braintree, MercadoPago, Paystack, and many more, but as noted above only Stripe is wired today. - Environment —
TestorLive. Set per-account, not globally. Most tenants keep one test account and one live account side by side and route real traffic only to the live one.
Provider and environment are locked once the account is saved — to switch, delete the row and add a new one.
Credentials
- API key — your Stripe secret key (
sk_test_…for test,sk_live_…for live). Encrypted at rest using the platform's AES key; the value is never returned to the browser after save. On the edit screen the field appears blank with a "leave empty to keep" hint. - Publishable key — optional, used by client-side flows. Stripe-format hint shown when provider is Stripe.
- Webhook secret — the
whsec_…signing secret. You can paste it now (manual flow) or leave it blank and have BetterSuite provision the endpoint for you (next step).
Configuration
- Account ref — your own label or external reference for this account. Free-text.
- Regions — the regions this account is allowed to serve. A payment flow that lands in a region without a matching PSP account is rejected.
- Return URL template — where Stripe redirects after a 3DS / off-session confirmation. Leave blank to use the platform default.
Click Save changes. On success, the form remains open so you can move on to webhook setup.
Step 2: Set up the webhook
After save, scroll to the Webhook Setup section. The console shows the exact endpoint URL — it looks like:
https://api.bettersuite.io/webhooks/<tenant-id>/<psp-account-id>
You can wire this up two ways:
Automatic (Stripe only)
Click Provision automatically. Using the API key you saved, BetterSuite calls Stripe, registers the endpoint, subscribes it to the events listed below, and stores the returned signing secret back into the account row. You'll get a "Webhook configured. Signing secret stored." toast on success.
There's also an opt-in "Auto-provision webhook after creation" checkbox in the credentials section when you first create a Stripe account — tick it and the same provisioning runs the moment the account is saved.
Manual
In Stripe Dashboard → Developers → Webhooks → Add endpoint:
- Paste the URL shown in the BetterSuite console.
- Subscribe to these events:
| Event |
|---|
payment_intent.succeeded |
payment_intent.payment_failed |
payment_intent.canceled |
payment_intent.processing |
payment_intent.requires_action |
payment_intent.amount_capturable_updated |
charge.refunded |
charge.refund.updated |
payment_method.attached |
payment_method.detached |
charge.dispute.created |
charge.dispute.updated |
charge.dispute.closed |
- Copy the signing secret Stripe shows you (starts with
whsec_), paste it into the Webhook secret field, and save.
The auto-provision path subscribes to exactly the same event list — keep the manual list in sync if you ever extend the handler in the backend.
Step 3: Verify it works
Hit Test connection in the page header. The console runs a small probe against Stripe with your saved key and shows a Connection OK / Connection failed dialog with latency in milliseconds. A failure here almost always means a typo'd API key or a deleted Stripe restricted-key.
To verify charges end-to-end, place a real test trip or order with the dashboard pointed at the Test PSP account and watch Stripe's Test data view for the corresponding payment_intent. Stripe's standard test cards (4242 4242 4242 4242 for a success, 4000 0025 0000 3155 for 3DS, 4000 0000 0000 9995 for a decline) work as documented at stripe.com/docs/testing.
Step 4: Pay out to drivers and vendors
Inbound charges only need the tenant's PSP account. Payouts to drivers, vendors, or service providers go through Stripe Connect Express, with a separate OAuth flow per recipient.
The flow lives in the driver / vendor onboarding screens (not the tenant Ops Console):
- The driver or vendor app calls
initiateStripeConnect, which mints a CSRF-safe OAuth state and returns a Stripe authorization URL. - The recipient signs in to Stripe (or creates an Express account inline), confirms the scope, and is redirected back through
/payout/stripe/callback. completeStripeConnectexchanges the code, persists the connected Express account ID against the recipient, and they're ready to receive payouts.
You never see the recipient's bank details — Stripe holds them; BetterSuite holds the Express account ID. Tenant-side payout scheduling lives in Ops Console → Payouts → Payout Sessions; the matching method registrations live in Ops Console → Payouts → Payout Methods.
Hiding an account without deleting it
The detail page has Hide / Show in the header — toggles the enabled flag. Hidden accounts stay in the database but stop being picked up by the payment router. Useful for retiring an account without losing its history.
Fees
BetterSuite doesn't take a cut of card processing — you pay Stripe directly at their published rates. The platform fee on transfers to Connect Express accounts depends on your plan and is disclosed in your contract.
What's next
- AI Providers — separate BYOK setup on the owner dashboard side.
- Email Sending — payment receipts ride on top of the tenant's outbound email path.
- Plans & Billing — the BetterSuite subscription, distinct from anything that flows through Stripe Connect.
