Stripe Payments

Connect a Stripe account so you can charge customers and pay out drivers, vendors, or providers.

Last updated Oct 1, 2026

Stripe is the only fully-implemented PSP in BetterSuite today. Connecting it lets your workspace 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 dashboard.
  • Your operating cities set in the dashboard. The gateway picker ranks providers by the countries you operate in, so it can tell you which ones reach your customers.

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 Payments → PSP Accounts, click Add PSP Account. The dialog has three parts:

Gateway and environment

  • Payment gateway — pick Stripe. The picker lists the other gateways too, with the countries each one operates in, but as noted above only Stripe is wired today.
  • Environment — Test or Live. Set per-account, not globally. Most operators keep one test account and one live account side by side and route real traffic only to the live one.

Gateway and environment are fixed 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. When you edit the account later the field is blank, and leaving it blank keeps the stored key.
  • Publishable key — optional, used by client-side flows.
  • 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).
  • Stripe Connect OAuth Client ID — needed only if drivers or vendors will onboard for payouts through Stripe Connect (Step 4).

Reference

  • Account reference — your own label or external reference for this account. Free-text, optional.

Save. The account appears in the list with its environment, the payment methods Stripe has enabled on it, and its status.

Step 2: Set up the webhook

BetterSuite receives Stripe events at one endpoint per PSP account:

https://api.bettersuite.io/webhooks/<workspace-id>/<psp-account-id>

You can wire this up two ways:

Automatic (Stripe only)

Open the account with Edit credentials and 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 see "Webhook configured. Signing secret stored." on success.

There's also an opt-in "Auto-provision webhook after creation" checkbox when you first create a Stripe account — tick it, leave the webhook secret blank, and the same provisioning runs the moment the account is saved.

Manual

The automatic route is the practical one: the dashboard doesn't print the endpoint URL, so a manual setup means building it from the pattern above. If you need to register it by hand, open a Support ticket and we'll confirm the two IDs. Then, in Stripe Dashboard → Developers → Webhooks → Add endpoint:

  1. Paste the endpoint URL.
  2. 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
  1. 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

Use the refresh action on the account's row. BetterSuite asks Stripe which payment methods the account is enabled for and shows them in the Payment methods column with the time they were checked. If the refresh fails, it is almost always a typo'd API key or a deleted Stripe restricted-key.

To verify charges end-to-end, place a real test trip or order while the Test PSP account is the active one 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 workspace'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 of their apps, not in the dashboard:

  1. The driver or vendor app calls initiateStripeConnect, which mints a CSRF-safe OAuth state and returns a Stripe authorization URL.
  2. The recipient signs in to Stripe (or creates an Express account inline), confirms the scope, and is redirected back through /payout/stripe/callback.
  3. completeStripeConnect exchanges 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. Which payout methods recipients can choose from is set in Payments → Payout Methods, where each method is bound to one of your PSP accounts.

Disabling an account without deleting it

Each row has a Disable / Enable action — it toggles the enabled flag. Disabled 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, under Configuration → AI.
  • Email Sending — payment receipts ride on top of the workspace's outbound email path.
  • Plans & Billing — the BetterSuite subscription, distinct from anything that flows through Stripe Connect.