Mitc.Integrations.Stripe

A turnkey Stripe integration library for ASP.NET Core applications. Handles webhook processing, product/price catalog syncing, 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,
    "EnableCatalogSync": true,
    "SyncInterval": "01: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):

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

Upgrading: 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.

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)