Skip to content
Emdash Mika Docs

Stripe Provider

Use this guide when Stripe is the host checkout provider.

The Stripe adapter is optional. Hosts using it install Stripe, create a Stripe client, supply the webhook secret, and keep SDK objects, credentials, retries, tax, shipping, and compliance rules in the host app.

Install Stripe alongside Mika when the host chooses this adapter:

Terminal window
npm install stripe

Typical host environment variables:

Terminal window
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

Create the Stripe SDK client in a server-only host module, not in an Astro component, browser island, or public client file:

src/lib/providers/stripe.ts
import Stripe from "stripe";
import { createMikaStripeProvider } from "@bnomei/emdash-mika/stripe";


const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);


export const stripeProvider = createMikaStripeProvider({
  stripe,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
});

src/lib/providers/stripe.ts should only be imported by trusted backend wiring, such as src/lib/mika-api.ts, a native EmDash plugin entrypoint, server endpoints, or Astro Actions. Do not import it from hydrated framework components, browser-side scripts, or code that uses @bnomei/emdash-mika/client.

Register The Provider

Section titled “Register The Provider”

Add the adapter to a provider registry and pass it to the backend API. The registry is how checkout, portal, refund, and webhook verification reach Stripe:

The backend-dependencies import below stands for the host-owned repository ports, ID factory, clock, and hash helper required by createMikaBackendApi().

src/lib/mika-api.ts
import { createMikaProviderRegistry } from "@bnomei/emdash-mika/provider";
import { createMikaBackendApi } from "@bnomei/emdash-mika/server";
import { createId, hash, now, repositories } from "./backend-dependencies";
import { stripeProvider } from "./providers/stripe";


export const api = createMikaBackendApi({
  repositories,
  providers: createMikaProviderRegistry([stripeProvider]),
  createId,
  now,
  hash,
  // notifications, defaults, config ...
});

This registration runs in the host server runtime when src/lib/mika-api.ts is evaluated. The Stripe SDK object is kept inside the backend API and provider registry; Mika does not serialize it into public plugin JSON, agent manifests, copied pages, or browser clients.

STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET are host environment configuration. The secret key creates the server-side Stripe SDK client. The webhook secret backs the adapter’s verifyWebhook(); the host webhook endpoint calls Mika.webhook.receive, and Mika’s backend invokes the registered adapter during verification. See the Backend And Provider guide.

The adapter reports capabilities from the Stripe-shaped client the host provides. Hosted checkout needs stripe.checkout.sessions; delegated ACP payments need stripe.paymentIntents.create; portal links need stripe.billingPortal.sessions; invoice links need stripe.invoices; refunds need stripe.refunds; webhook signatures need both webhookSecret and stripe.webhooks.constructEvent.

Webhook verification requires the raw request body and the Stripe-Signature header. Do not parse and reserialize the body before it reaches Mika.webhook.receive; the provider adapter verifies the original bytes and returns a payload hash used by Mika’s webhook workflow.

For a production webhook and checkout-return checklist, see Stripe And Webhook Cookbook.

Boundary

Section titled “Boundary”

Mika’s provider contract stays provider-neutral. Stripe field names belong in the adapter and projection layers, not in core catalog, cart, checkout, or order semantics.

Verify

Section titled “Verify”
  • The Stripe SDK client is created only in a server module.
  • The provider registry reports hosted checkout and webhook signature capabilities when the host supplies the required Stripe resources and secrets.
  • Checkout start returns a hosted provider redirect or a clear provider/configuration error.
  • The webhook endpoint preserves the raw request body and receives Stripe-Signature.

Next: Stripe And Webhook Cookbook covers raw-body verification and return checks. Stripe lists exact adapter behavior.

External References

Section titled “External References”

Source Anchors

Section titled “Source Anchors”
  • ⓟ ../emdash-mika/src/stripe.ts
  • ⓟ ../emdash-mika/src/provider.ts
  • ⓐ ../emdash-mika/src/templates/astro/pages/api/mika-webhook/[provider].ts
  • ⓐ ../emdash-mika/src/templates/astro/examples/backend-provider.md