Provider Contract

Use @bnomei/emdash-mika/provider to define and register payment or commerce provider adapters.

Provider adapter means server-only translator: it turns Mika’s provider-neutral checkout, portal, invoice, refund, sync, subscription, and webhook contract into calls to a real service such as Stripe, Paddle, Lemon Squeezy, or a custom backend.

A complete adapter handles provider-specific checkout sessions, portal sessions, invoice lookup, subscription actions, refunds, catalog sync, webhook verification, and webhook event parsing.

Core Exports

Export	Role
MikaProviderAdapter	Interface implemented by a provider adapter.
MikaProviderRegistry	Lookup table keyed by provider name.
defineMikaProvider(adapter)	Identity helper for authoring adapters with type inference.
createMikaProviderRegistry(providers)	Builds the registry consumed by backend APIs.
MikaProviderCheckoutInput	Normalized checkout creation input from Mika cart lines.
MikaProviderCheckoutSession	Normalized provider checkout session returned by create/retrieve.
MikaProviderWebhookVerificationInput	Raw webhook request plus raw body for signature verification.
MikaVerifiedWebhookPayload	Verified raw body, payload hash, headers, and parsed JSON.
MikaProviderWebhookEvent	Payment, subscription, or unknown event normalized for Mika workflows.
MIKA_DELEGATED_PAYMENT_TOKEN_METADATA_KEY	Checkout metadata key carrying an ACP delegated payment token.
MIKA_DELEGATED_PAYMENT_PROVIDER_METADATA_KEY	Checkout metadata key naming the delegated payment provider.
MIKA_DELEGATED_PAYMENT_AUTHORIZATION_METADATA_KEY	Checkout metadata key storing the delegated payment authorization id.
MIKA_DELEGATED_PAYMENT_AUTHORIZATION_INPUT_HASH_METADATA_KEY	Checkout metadata key binding delegated checkout start to the preview authorization input hash.
MIKA_DELEGATED_PAYMENT_CHECKOUT_SESSION_ID_METADATA_KEY	Checkout metadata key linking provider payment back to the ACP checkout session.

Adapter Shape

Required methods:

• capabilities();
• createCheckoutSession(input);
• retrieveCheckoutSession(id).

Optional methods:

• health();
• createPortalSession(input);
• getInvoiceUrl(input);
• cancelSubscription(input);
• changeSubscription(input);
• renewSubscription(input);
• refundPayment(input);
• cancelOrder(input);
• syncCatalog(input);
• verifyWebhook(input);
• parseWebhookEvent(input).

The backend checks provider capabilities before operations that require a specific feature. For optional admin-action methods (cancelSubscription, changeSubscription, renewSubscription, refundPayment, cancelOrder, syncCatalog), unsupported implementations return an AdminActionResultDTO. Other optional methods can be omitted or follow their own return contract.

Capabilities

Provider capabilities are exported through the shared types surface:

• hosted_checkout;
• payments;
• subscriptions;
• subscription_renew;
• subscription_change;
• subscription_cancel;
• portal;
• invoice_url;
• refunds;
• coupons;
• product_sync;
• variant_sync;
• stock_sync;
• webhook_signatures.

ProviderHealthDTO reports the provider id, ok, capabilities, and optional warnings.

Checkout Mapping

MikaProviderCheckoutInput contains the provider name, purchase mode, customer snapshot, cart lines, optional order-level discount, success/cancel URLs, and metadata. Lines carry Mika sellable/price/content references plus optional provider product/price ids. Adapters are responsible for converting those lines into the provider’s checkout/session/payment API.

MikaProviderCheckoutSession returns Mika-normalized status, mode, provider, optional redirect URL, expiration, provider checkout/customer ids, and optional raw provider data.

Delegated ACP payment handoff uses provider-neutral metadata keys exported from this subpath. The current key values are acpPaymentToken, acpPaymentProvider, acpPaymentAuthorizationId, acpPaymentAuthorizationInputHash, and acpCheckoutSessionId. Stripe re-exports provider-specific aliases for the first three keys, but the canonical constants live in @bnomei/emdash-mika/provider.

Webhook Mapping

Webhook verification and parsing are split:

• verifyWebhook() receives the Request and raw body, performs provider-specific signature checks, and returns a verified payload plus payloadHash;
• parseWebhookEvent() maps the verified provider payload into payment, subscription, or unknown events.

Mika’s backend uses normalized payment and subscription events to reconcile orders, entitlements, subscriptions, failures, and webhook replay behavior. The host still owns provider webhook endpoint deployment and provider secret configuration.

Registry

createMikaProviderRegistry([adapter]) stores adapters by adapter.id and exposes get(provider) and list(). Pass the registry into createMikaBackendApi() through backend dependencies.

Minimal Custom Provider

import { defineMikaProvider } from "@bnomei/emdash-mika/provider";
import { createProviderName } from "@bnomei/emdash-mika/types";

export const customProvider = defineMikaProvider({
  id: createProviderName("custom"),
  async capabilities() {
    return ["hosted_checkout", "payments"];
  },
  async createCheckoutSession(input) {
    return {
      id: "provider_checkout_123",
      provider: createProviderName("custom"),
      status: "pending",
      mode: input.mode,
      redirectUrl: "https://provider.example/checkout/provider_checkout_123",
    };
  },
  async retrieveCheckoutSession(id) {
    return {
      id,
      provider: createProviderName("custom"),
      status: "pending",
      mode: "payment",
    };
  },
});

Add webhook, portal, invoice, refund, subscription, and sync methods only when the provider supports those capabilities and the host has the matching storage, secrets, and policy.

Stripe Adapter

@bnomei/emdash-mika/stripe provides an optional Stripe implementation via createMikaStripeProvider(). It accepts a host-injected Stripe-shaped client and only advertises capabilities for client surfaces that exist, such as checkout sessions, payment intents, subscriptions, billing portal, invoices, refunds, coupons, catalog sync, and webhook signatures.

The Stripe adapter does not create Stripe credentials, tax rules, shipping rates, products, or webhook endpoint configuration. Those remain host-owned.

Source Anchors

• ⓟ ../emdash-mika/src/provider.ts
• ⓟ ../emdash-mika/src/api/types.ts
• ⓟ ../emdash-mika/src/api/backend.ts
• ⓟ ../emdash-mika/src/stripe.ts