Migrate from Stripe
Move Stripe checkout, refunds and webhooks onto MainSDK pay with hosted checkout, idempotency keys and verified webhooks.
Status Status is where the work is: Planned (in a milestone, not started), Building (tickets in progress), Preview (usable, may change), then the stability it ships at.
Stability The promise an interface ships with.
- Stable Follows semantic versioning; breaking changes need a new major, 12 months of overlap and a codemod.
- Beta Usable in production; may change before it becomes stable.
- Experimental May change or go away; needs an explicit opt-in in main.yaml.
Move Stripe checkout, refunds and webhooks onto MainSDK pay with hosted checkout, idempotency keys and verified webhooks. Your Stripe account stays; nothing here deletes it.
Before you start:
- A git repository with a clean working tree.
mainsdk migrateworks on a branch and never touches yours. - Node 22 and
npx mainsdk. Nomain.yamlyet?migratewrites one; or start with Adopt an existing app. - Your Stripe keys stay where they are. Move them to
secret:references when the driver is chosen (see Secrets).
1. Read the report
npx mainsdk migrate stripe --report-onlyThe report writes no file. It sorts every Stripe call in your code into three lists: mapped (an interface call replaces it), raw (it stays behind raw(), with the reason) and needs a person (a policy, a rule file or a call with no interface). Add --json for a machine-readable report.
For the sample app of this guide (packages/cli/test/fixtures/migrate/stripe), the report finds 3 mapped, 0 raw and 0 for a person.
2. What the codemod changes
| Where | Before | After |
|---|---|---|
app/api/checkout/route.ts:5 | const session = await stripe.checkout.sessions.create({ | pay.checkout() |
app/api/refund/route.ts:5 | return Response.json(await stripe.refunds.create({ charge })) | pay.refund() |
app/api/webhook/route.ts:4 | const event = stripe.webhooks.constructEvent( | pay.webhook() |
Each rewrite is mechanical and one line at a time. Imports of Stripe go when no call needs them, and mainsdk is added to package.json.
3. What stays behind raw()
- Nothing in the sample stays behind raw().
A call behind raw() keeps working through the Stripe host on your network allow list, and mainsdk check still sees it. Each one has a marker comment, // mainsdk migrate: ..., so you can find it later.
4. What needs a person
- Nothing in the sample needs a person.
The codemod leaves these lines alone and marks them. No tool should guess a policy.
5. Stateful moves are guided jobs
Data does not move with the code. Each stateful move is a job with steps and a rollback, listed in the pull request and never run by the codemod.
webhooks: Point the Stripe webhook endpoint at the verified MainSDK route
- Add the new endpoint in the Stripe dashboard with its own signing secret, stored as a secret: reference.
- Send test events and compare the audit log with the old endpoint.
- Keep both endpoints for seven days, then remove the old one.
Rollback: Re-enable the old endpoint; Stripe delivers to both, handlers are idempotent.
customers: Customers and subscriptions stay in Stripe; the driver reads them
- Set pay.driver: stripe with the live key as a secret: reference.
- Run one test-mode checkout end to end.
Rollback: Revert the pull request; no Stripe data moved.
6. Open the pull request
npx mainsdk migrate stripeThis records your sign-in and checkout flows as locked flows first, then creates the branch migrate/stripe, applies the codemods, adds .github/workflows/mainsdk-migrate.yml, runs mainsdk check and the locked flows, commits, pushes and opens one pull request with gh. If a gate fails, the branch is kept and no pull request opens (MAIN-MIGRATE-0001). --no-pr stops after the commit.
Locked flows run again in CI: npx mainsdk migrate flows.
Where you end
You end at the reference architecture mainsdk/payments-checkout: the same shape, with its tests, benchmark and chaos drills.
npx mainsdk init --template mainsdk/payments-checkoutWas this page helpful?