Stripe Connect platform setup

A step-by-step checklist for the Stripe Dashboard actions needed to make shipsafe-mcp-pay work in live mode with real merchants. The code is built to work in test mode today; live mode requires Stripe's approval and a handful of dashboard switches.

This is a one-time setup. Budget ~30 minutes to click through everything, then 24–48 hours for Stripe to review the platform application.

What you're enabling

Stripe Connect Express lets each merchant onboard their own Stripe account under your platform. You take an application_fee_amount on each top-up; the rest lands in the merchant's balance. Stripe needs you to apply for "platform" status before it'll let you create live-mode Connect accounts.

Prerequisites

• A Stripe account in good standing (test mode works today; live mode requires this checklist).
• Access to shipsafe-web Vercel project for setting environment variables.
• The webhook signing secret from Stripe (created in step 4).

Step 1 — Enable Connect on your Stripe account

1. Open the Stripe Dashboard.
2. Navigate to Settings → Connect → Get started with Connect.
3. Choose Platform or marketplace.
4. When asked "How will you use Connect?", select Build a SaaS platform (closest match for shipsafe-mcp-pay).
5. Save and continue.

Step 2 — Configure your platform profile

Fill in the platform profile under Settings → Connect → Settings:

Field	What to put
Platform name	ShipSafe (or whatever you brand the payments product as)
Platform website	https://shipsafe.franklabs.io/pay
Description	"Multi-tenant payments middleware for MCP servers — agents pay per tool call."
Industry	Software / SaaS
Country	United States
Platform type	Express (we use Express, not Custom or Standard)
Branding	Upload the ShipSafe logo for the Stripe-hosted onboarding pages

Save changes.

Step 3 — Submit the live-mode platform application

Stripe doesn't let you create live-mode Connect accounts until they approve your platform.

1. From Settings → Connect → Apply for live, click Start application.

2. Fill in business details (legal entity, address, tax ID, banking info).

3. Describe your platform model in plain English. Suggested text:

   shipsafe-mcp-pay is a payments middleware for AI agent developers. Developers register as merchants, link their Stripe Express accounts, and use our shipsafe-mcp-pay npm package to charge their customers per MCP tool call. We take a 10% application fee on customer wallet top-ups; the remainder flows to the merchant. Customer wallets are prepaid; tool-call debits happen against the wallet, not Stripe.

4. Submit. Stripe usually responds in 24–48 hours; sometimes faster.

While you wait, everything works in test mode — no need to block development.

Step 4 — Set up the Connect webhook endpoint

Connect events (top-up succeeded, account updated, refund issued) are delivered separately from regular Stripe events. You need a Connect-specific webhook.

1. Stripe Dashboard → Developers → Webhooks.
2. Click Add endpoint.
3. URL: https://shipsafe.franklabs.io/api/mcp-pay/webhook (replace with your production domain if different).
4. CRITICAL: under "Listen to", toggle Events on Connected accounts (not "Events on your account"). This is the difference between Connect events and platform events; getting it wrong means your webhook gets zero useful traffic.
5. Select events:
   • payment_intent.succeeded — the top-up landed; credit the wallet.
   • account.updated — the merchant finished onboarding or had a state change.
   • charge.refunded — refund issued at the Stripe level; reverse the wallet credit.
6. Save. Stripe shows you a signing secret (whsec_...).
7. Open the Vercel dashboard → shipsafe-web → Settings → Environment Variables.
8. Add: STRIPE_CONNECT_WEBHOOK_SECRET=whsec_... (Production only — leave Preview and Development unset).
9. Trigger a new deploy so the env var takes effect.

Until this secret is set, the webhook endpoint returns 500 on every Connect event. Until a merchant onboards, no events will fire — so you can defer this step right up until your first live merchant.

Step 5 — Set the platform-side env vars on Vercel

Even before live mode is approved, you'll want these set so test-mode flows work end-to-end:

Variable	Value	Purpose
STRIPE_SECRET_KEY	sk_live_... (or sk_test_...)	Platform-side Stripe SDK auth
STRIPE_CONNECT_WEBHOOK_SECRET	whsec_... from step 4	Connect webhook signature verification
MCP_PAY_DEFAULT_FEE_BPS	1000	Platform default application fee (10%). Omit to use the in-code fallback.
MCP_PAY_AUTO_APPROVE_USER_IDS	<your-auth-user-uuid>	Your own merchants auto-approve. CSV for multiple platform owners.
MCP_PAY_ADMIN_USER_IDS	<your-auth-user-uuid>	Who can access /admin/merchants. CSV.

The last three are platform-controls, not Stripe-required; the Stripe ones are.

Step 6 — Verify in test mode (do this NOW, don't wait for approval)

1. Set the env vars from step 5 with sk_test_ and whsec_ (test).
2. Sign up at /merchants/new as yourself. With your user_id in MCP_PAY_AUTO_APPROVE_USER_IDS, your merchant lands as approved immediately.
3. Walk through Stripe Connect Express onboarding using Stripe's test data (no real bank info needed in test mode).
4. Declare a tool on /merchants/<your-id>, issue a test API key (mp_test_...).
5. Top up a wallet via /api/mcp-pay/topup/intent and pay with Stripe's test card 4242 4242 4242 4242.
6. Confirm in the Stripe Dashboard that the application_fee_amount landed in your platform balance and the rest landed in the merchant's Connect balance.

If steps 1–6 work, you've proven the flow end-to-end. Live mode is the same thing with sk_live_ and a real card.

Step 7 — Once Stripe approves live mode

1. Replace sk_test_ env vars with sk_live_ versions.
2. Create a NEW Connect webhook in live mode (Stripe doesn't share secrets between modes); replace STRIPE_CONNECT_WEBHOOK_SECRET with the live whsec_.
3. Deploy.
4. Tell your first real merchant to sign up.

Troubleshooting

Webhook returns 500 in production. Almost always: STRIPE_CONNECT_WEBHOOK_SECRET is wrong or unset. Check Vercel env vars; check that you used the secret from the Connect webhook (step 4), not the regular platform webhook.

Merchant can't complete onboarding. Express onboarding requires Stripe to verify the merchant's identity and bank. Test mode skips most of this; live mode requires real data. If a merchant is stuck, check /admin/merchants/<id> → the connect_status will be one of pending / restricted / disabled. restricted means Stripe wants more info from them.

Application fee doesn't appear in my balance. Two common causes: (a) you're looking at the merchant's Connect dashboard instead of your platform dashboard, or (b) the fee was added but isn't paid out yet (Stripe payouts run on a schedule). Check the payment intent details directly to confirm application_fee_amount is set.

Stripe rejects the platform application. Most rejections are about business model unclarity. The description in step 3 covers it explicitly; if Stripe asks follow-up questions, point them at /pay and /docs/mcp-pay/architecture for the full model.