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",
    "TrialPeriodDays": 14
  }
}

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

The library provides entity classes that must be mapped in your DbContext. Add the following DbSet properties and configure them in OnModelCreating:

• StripeEvent
• StripeProduct / StripePrice
• StripeSubscription / StripeSubscriptionItem

4. Implement Required Interfaces

Stores — Inherit from the provided base classes, passing your application's DbContext:

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);

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

Use the builder callback to override any default store or event handler:

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 LocalUrlAndPort to be configured)