Mitc.Integrations.Stripe

A turnkey Stripe integration library for ASP.NET Core applications. Handles webhook processing, product/price catalog mirroring, missed-event backfill, subscription management, checkout session creation, and metered usage reporting.

Supported Frameworks

• .NET 9
• .NET 10

Setup

1. Configuration

Add a StripeOptions section to your appsettings.json:

{
  "StripeOptions": {
    "ApiKey": "sk_...",
    "EndpointSecret": "whsec_...",
    "RegistrationCompletedPage": "https://example.com/registration/complete",
    "RegistrationCancelledPage": "https://example.com/registration/cancelled",
    "AllowLiveEvents": true,
    "AllowTestEvents": false,
    "EnableEventReconciliation": true,
    "ReconciliationInterval": "01:00:00",
    "ReconciliationLookback": "1.00:00:00",
    "EnableUsageReporting": true,
    "ReportFrequency": "01:00:00",
    "EnableLocalWebhook": true,
    "ProcessingDelay": "00:00:05",
    "ProcessingInterval": "00:00:01",
    "EventCleanupInterval": "1.00:00:00",
    "EventRetentionPeriod": "30.00:00:00",
    "MaxEventRetries": 3,
    "EventRetryDelay": "00:00:20"
  }
}

2. Register Services

builder.SetupStripeIntegration<AppDbContext>();

The generic type parameter TDbContext must be your application's DbContext type. This allows the default store implementations to resolve your concrete DbContext from DI.

This registers all required services, background workers, and a webhook controller endpoint at POST /stripe/webhook.

3. EF Core Entity Configuration

Implement IStripeContext on your DbContext and call ConfigureStripeEntities in OnModelCreating:

public class AppDbContext : DbContext, IStripeContext
{
    public DbSet<StripeEvent> StripeEvents { get; init; }
    public DbSet<StripeProduct> StripeProducts { get; init; }
    public DbSet<StripePrice> StripePrices { get; init; }
    public DbSet<StripeCheckoutSession> StripeCheckoutSessions { get; init; }
    public DbSet<StripeSubscription> StripeSubscriptions { get; init; }
    public DbSet<StripeSubscriptionItem> StripeSubscriptionItems { get; init; }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.ConfigureStripeEntities();
    }
}

ConfigureStripeEntities configures string primary keys (Stripe-assigned, not auto-generated), StripeMetadataValueConverter on metadata properties, and navigation relationships (StripeProduct → StripePrice, StripeSubscription → StripeSubscriptionItem).

4. Implement Required Interfaces

Checkout session event handler — No default implementation is provided; you must supply one:

public class MyCheckoutHandler : IStripeCheckoutSessionEventHandler
{
    public Task<Outcome> HandleCheckoutSessionCompleted(Session session) { /* ... */ }
    public Task<Outcome> HandleCheckoutSessionExpired(Session session) { /* ... */ }

    // Async (delayed) payment methods fire async_payment_succeeded / async_payment_failed.
    // Both default to a no-op success, so only override them if you accept such methods:
    // public Task<Outcome> HandleCheckoutSessionAsyncPaymentSucceeded(Session session) { /* ... */ }
    // public Task<Outcome> HandleCheckoutSessionAsyncPaymentFailed(Session session) { /* ... */ }
}

Usage report generator — Required by the usage reporting service. Return one SubscriberUsage per active subscription item. Only include active, non-cancelled subscriptions; cancelled or ended subscriptions should be filtered out by your query:

public class MyUsageReportGenerator : IStripeUsageReportGenerator
{
    public Task<IEnumerable<SubscriberUsage>> GetUsagesAsync() { /* ... */ }
}

Customizing Services

Default store implementations are provided and registered automatically. Custom stores are only needed if you require behavior beyond the defaults. The default stores expose virtual members, so you can inherit one and override only the methods you need:

public class MyStripeEventStore(AppDbContext db) : StripeEventStore(db);
public class MyStripeProductStore(AppDbContext db) : StripeProductStore(db);
public class MyStripePriceStore(AppDbContext db) : StripePriceStore(db);
public class MyStripeSubscriptionStore(AppDbContext db) : StripeSubscriptionStore(db);

Or implement the store interfaces (IStripeEventStore, IStripeProductStore, etc.) directly for full control.

Use the builder callback to register custom stores or event handlers:

builder.SetupStripeIntegration<AppDbContext>(stripe => stripe
    .AddEventStore<MyStripeEventStore>()
    .AddProductStore<MyStripeProductStore>()
    .AddPriceStore<MyStripePriceStore>()
    .AddSubscriptionStore<MyStripeSubscriptionStore>()
    .AddCheckoutSessionEventHandler<MyCheckoutHandler>()
);

Builder overrides are registered before the library's defaults, so TryAddScoped will skip any service you've already configured.

Available Builder Methods

Stores (scoped, depend on DbContext):

Event handlers (scoped):

Sources (singleton):

Architecture

Event Processing Pipeline

Stripe webhook
  -> StripeController (POST /stripe/webhook)
    -> IStripeEventParser (signature verification)
    -> Event.IsForEnabledMode (live/test filter; ignored events are acked and dropped)
    -> IStripeEventStore.AddAsync (idempotent durable insert — 200 OK only after the row commits)

StripeEventProcessor (background service, periodic)
  -> IStripeEventStore.GetProcessableEventsAsync (settled + due events)
  -> IStripe*EventHandler (handle by type, in dependency order)

Events are persisted at intake and become processable only after they have aged past ProcessingDelay (the settle window, keyed off arrival time). This lets a burst of out-of-order events finish arriving before the processor sorts and applies them by (Created, tier, id). Dedup is a primary-key guarantee: a redelivered event id is swallowed on insert.

Because every event is durable before the webhook is acked, ProcessingDelay is purely a query delay rather than an in-memory hold — it can be lengthened to absorb larger or more out-of-order bursts with no added risk of data loss.

Background Services

Recovery semantics

Stale snapshot events (product/price/subscription) are skipped when a newer event for the same object has already been processed — applying an older point-in-time snapshot would regress local state. If you replace a snapshot handler with one that performs side effects, be aware that superseded events are marked processed without invoking your handler. Checkout-session events are never skipped: each type carries a distinct side effect, so a backfilled checkout.session.completed still runs even if a later session event was already handled.

A non-empty backfill is logged at Warning level — it means webhook delivery missed something. Check the endpoint configuration in the Stripe dashboard.

Upgrading to 3.0

Upgrading from 1.x? Apply the 2.0 migration notes below as well.

• StripeEvent gained an ObjectId column (indexed) — add an EF migration in your application. Rows persisted before the migration have a NULL ObjectId, so events backfilled shortly after upgrading may not be recognized as superseded until the next boot re-seeds the catalog.
• StripeOfferingSyncService, EnableCatalogSync, and SyncInterval were removed. Boot-time seeding replaces the periodic sync and is always on; remove the deleted keys from configuration.
• IStripeEventStore gained HasNewerProcessedEventAsync and GetMissingIdsAsync; IStripeProductStore/IStripePriceStore gained UpsertRangeAsync. Custom store implementations must add these members.

Upgrading to 2.0

• This version adds a ReceivedAt column to the StripeEvent entity. Consuming applications must add and apply an EF Core migration (dotnet ef migrations add AddStripeEventReceivedAt) against their own DbContext.

Handled Webhook Events

Metadata

StripeMetadata provides strongly-typed access to Stripe metadata dictionaries via DataKey<T>:

public static readonly DataKey<Guid> RegistrationId = new("registration_id");

// Writing
var metadata = new StripeMetadata();
metadata.Add(RegistrationId, someGuid);

// Reading
Guid id = metadata.Get(RegistrationId);
Guid? maybeId = metadata.TryGet(RegistrationId);

Includes an EF Core ValueConverter (StripeMetadataValueConverter) for database persistence.

Webhook configuration check

A webhook endpoint that is disabled, points at the wrong URL, or isn't subscribed to an event type fails silently: Stripe never attempts delivery, so nothing shows up as a failed delivery. At startup the library lists the account's webhook endpoints and verifies that an endpoint matches this app (WebhookEndpointUrl, or the /stripe/webhook URL suffix), that it is enabled, and that its enabled_events covers every event type the library routes (["*"] counts as full coverage). Findings are logged — startup is never blocked, and the event reconciler remains the runtime safety net.

With WebhookConfigurationMode: "Heal", the check additionally repairs the one misconfiguration that is both common and silent: missing event types. The repair writes the union of the endpoint's existing enabled_events and the library's routed types — it only ever adds types. Healing never removes types, never touches ["*"] endpoints, never re-enables a disabled endpoint (auto-disable is a symptom of delivery failures; investigate those first), never creates an endpoint, and never touches the endpoint secret. It also refuses to act when several endpoints match — set WebhookEndpointUrl to identify the right one. Teams managing Stripe configuration as code (e.g. Terraform) should leave the mode at Validate.

A restricted API key without webhook-endpoint read permission degrades the check to a "could not verify" warning; a key that can read but not write logs the findings and a warning that healing was denied.

Checkout

IStripeOperations creates Stripe Checkout sessions for both subscriptions and one-time payments. The mode is selected automatically from the price: a recurring price creates a subscription, a one-time price creates a payment.

public class MyService(IStripeOperations operations)
{
    public async Task StartCheckout(ICheckoutRequest request, StripeMetadata metadata)
    {
        var session = await operations.CreateCheckoutSessionAsync(request, metadata);
        // Redirect user to session.Url
    }
}

The provided metadata is attached to the checkout session and, depending on the mode, the resulting subscription or payment intent.

Local Development

When builder.Environment.IsDevelopment() is true, the library:

• Bypasses Stripe webhook signature verification
• Starts a StripeLocalEventListener that uses the Stripe CLI to forward events to your local server (requires the Stripe CLI to be installed and EnableLocalWebhook to be set to true)