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,
    "SyncInterval": "01:00:00",
    "ReportFrequency": "01:00:00",
    "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();

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