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 8
• .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 HandleCheckoutSessionCompleted(Session session) { /* ... */ }
    public Task HandleCheckoutSessionExpired(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. To customize, inherit from the provided base classes:

public class MyStripeEventStore(AppDbContext db) : StripeEventStoreBase(db);
public class MyStripeProductStore(AppDbContext db) : StripeProductStoreBase(db);
public class MyStripePriceStore(AppDbContext db) : StripePriceStoreBase(db);
public class MyStripeSubscriptionStore(AppDbContext db) : StripeSubscriptionStoreBase(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)
      -> IStripeEventDispatcher (deduplication + delay queue)
        -> StripeEventProcessor (background service, periodic drain)
          -> IStripeEventStore (persist)
          -> IStripe*EventHandler (handle by type)

Events are held in a priority queue for ProcessingDelay before processing. This allows out-of-order events to arrive and be grouped by object ID, ensuring related events are processed sequentially.

Background Services

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

IStripeCheckoutService creates Stripe Checkout sessions for subscriptions:

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

The provided metadata is attached to both the checkout session and the subscription.

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)