Skip to content
Emdash Mika Docs

Stripe

Use @bnomei/emdash-mika/stripe only when the host chooses Stripe.

Important surfaces include:

  • createMikaStripeProvider();
  • MIKA_STRIPE_PROVIDER_ID;
  • MIKA_STRIPE_DELEGATED_PAYMENT_TOKEN_METADATA_KEY;
  • MIKA_STRIPE_DELEGATED_PAYMENT_PROVIDER_METADATA_KEY;
  • MIKA_STRIPE_PAYMENT_AUTHORIZATION_METADATA_KEY;
  • MikaStripeClient;
  • CreateMikaStripeProviderOptions;
  • Stripe-shaped parameter/result interfaces used by the adapter.

Stripe remains optional. The host owns the real Stripe SDK client, credentials, webhook secret, retries, tax, shipping, and compliance behavior.

Adapter Inputs

Section titled “Adapter Inputs”

createMikaStripeProvider() accepts:

Option Role
stripe Host-injected Stripe-shaped client. This can be the real Stripe SDK or a test double matching Mika’s minimal surface.
id Optional provider id override. Defaults to stripe.
webhookSecret Secret used with stripe.webhooks.constructEvent() for webhook verification.
capabilities Optional explicit capability list. If omitted, Mika derives capabilities from available Stripe client surfaces.
catalogSync Optional host-provided catalog sync callback.
now Optional clock for health checks and timestamp mapping.

The minimal client shape includes only the Stripe APIs Mika may call: checkout sessions, payment intents, billing portal sessions, invoices, refunds, coupons, subscriptions, and webhook construction.

Derived Capabilities

Section titled “Derived Capabilities”

When capabilities is not provided, the adapter advertises capabilities based on the injected client:

Stripe client surface Capabilities
checkout.sessions hosted_checkout, payments
paymentIntents.create payments and delegated ACP payment support
subscriptions subscriptions, subscription_renew, subscription_change, subscription_cancel
billingPortal.sessions portal
invoices invoice_url
refunds refunds
webhookSecret plus webhooks.constructEvent webhook_signatures
catalogSync product_sync, variant_sync, stock_sync

health() reports ok when checkout sessions or payment intents are present and warns when the webhook secret is missing.

Checkout Behavior

Section titled “Checkout Behavior”

Hosted checkout uses stripe.checkout.sessions.create() with Mika line items, success/cancel URLs, optional customer email, metadata, and an idempotency key. If Mika passes an order-level discount, the adapter creates a single-use Stripe coupon and attaches it to the session. If coupons are unavailable, the adapter throws instead of creating a session that would charge the undiscounted subtotal.

Delegated ACP payment is triggered when checkout metadata contains acpPaymentToken. In that case the adapter uses stripe.paymentIntents.create() with shared_payment_granted_token, subtracts any Mika discount from the subtotal, confirms the PaymentIntent, and maps the PaymentIntent back into a Mika provider checkout session.

Subscription cancellation maps to Stripe cancel_at_period_end: true, so Mika and Stripe keep entitlement access aligned until the period ends and a later subscription webhook finalizes the lifecycle.

Webhooks

Section titled “Webhooks”

verifyWebhook() requires:

  • the raw request body as Uint8Array;
  • the incoming stripe-signature header;
  • webhookSecret;
  • stripe.webhooks.constructEvent().

It returns payloadHash as sha256:<hex>, original headers, raw body, and the parsed Stripe event. parseWebhookEvent() normalizes supported Stripe event families into Mika provider events:

  • customer.subscription.* as subscription events;
  • payment_intent.payment_failed, checkout.session.async_payment_failed, and checkout.session.expired, and invoice.payment_failed as failed payment events;
  • charge.refunded as refunded or partially refunded payment events;
  • invoice.marked_uncollectible as a refunded payment event;
  • paid invoices as payment events;
  • succeeded payment intents as payment events;
  • paid checkout sessions and async checkout successes as payment events;
  • everything else as unknown.

For Stripe API and webhook behavior, see the official Stripe API docs and Stripe webhook docs. For raw-body signature verification, see Stripe’s webhook signature guide.

Source Anchors

Section titled “Source Anchors”
  • ⓟ ../emdash-mika/src/stripe.ts
  • ⓟ ../emdash-mika/src/provider.ts
  • ⓟ ../emdash-mika/src/acp.ts