Paymentify 1.5.3

Paymentify

A drop-in .NET 10 library that integrates Dodo Payments subscriptions into any ASP.NET Core app. Handles webhooks, local subscription state, built-in pricing/billing pages, and authorization gating — wired up in two method calls.

Namespaces

Quick start

1. Add your DbContext (must implement IPaymentifyDbContext and call AddPaymentifyEntities in OnModelCreating):

using Microsoft.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore.ChangeTracking;
using Paymentify.Data;
using Paymentify.Data.Entities;
using Paymentify.Extensions;

public class AppDbContext(DbContextOptions<AppDbContext> options)
    : DbContext(options), IPaymentifyDbContext
{
    // IPaymentifyDbContext — expose these four sets
    public DbSet<LocalSubscription> Subscriptions => Set<LocalSubscription>();
    public DbSet<LocalCustomer>     Customers      => Set<LocalCustomer>();
    public DbSet<WebhookEvent>      WebhookEvents  => Set<WebhookEvent>();
    public DbSet<PurchaseInterest>  PurchaseInterests => Set<PurchaseInterest>();
    EntityEntry IPaymentifyDbContext.Entry(object e) => Entry(e);

    protected override void OnModelCreating(ModelBuilder model)
    {
        // your own entity config...
        model.AddPaymentifyEntities(); // registers all Paymentify tables
    }
}

2. Register in Program.cs:

using System.Security.Claims;
using Microsoft.EntityFrameworkCore;
using Paymentify.Extensions;
using Paymentify.Options;

// Register your DbContext first (Paymentify reuses it)
builder.Services.AddDbContext<AppDbContext>(o =>
    o.UseSqlite("Data Source=app.db"));

builder.Services.AddRazorPages(); // required for built-in pricing/billing pages

builder.Services.AddPaymentify<AppDbContext>(opts =>
{
    opts.ApiKey        = builder.Configuration["Dodo:ApiKey"]!;
    opts.WebhookSecret = builder.Configuration["Dodo:WebhookSecret"]!;

    opts.UserIdResolver  = ctx => ctx.User.FindFirstValue(ClaimTypes.NameIdentifier);
    opts.EmailResolver   = ctx => ctx.User.FindFirstValue(ClaimTypes.Email);

    opts.Plans = [
        new() { ProductId = "prod_starter", Name = "Starter", PriceDisplay = "$9/mo" },
        new() { ProductId = "prod_pro",     Name = "Pro",     PriceDisplay = "$29/mo", Highlighted = true },
    ];
});

// ...

// Apply EF migrations at startup (host owns migrations)
using (var scope = app.Services.CreateScope())
    await scope.ServiceProvider.GetRequiredService<AppDbContext>().Database.MigrateAsync();

app.UseAuthentication();
app.UseAuthorization();
app.MapPaymentify("/paymentify");

3. Add an EF migration (first time, and after any schema change):

dotnet ef migrations add Init --project YourApp --context AppDbContext

Postgres users: always generate this migration against your own Postgres-configured AppDbContext. Don't copy samples/SampleApp/Migrations/* — those were scaffolded against SQLite, so they hard-code SQLite column types (TEXT, INTEGER) that Npgsql won't accept. Running dotnet ef migrations add against a Postgres provider produces correct native types (text, boolean, timestamp with time zone) automatically.

What you get

MapPaymentify only mounts the webhook route above. Checkout, portal, plan changes, cancellation, reactivation, and invoices are all handled in-process by the built-in Razor Pages calling SubscriptionService directly — there's no separate JSON API for them. Call SubscriptionService yourself (see below) if you need this outside the built-in pages.

Theming

The built-in pages ship structure only — they inherit your app's font and text color, never paint a page background, and derive borders and muted text from your theme automatically (including dark mode: if your pages are dark, so are Paymentify's). To brand them, set CSS variables on :root (or any ancestor):

:root {
  --pf-accent: #0d6efd;          /* primary buttons, featured plan — usually all you need */
  --pf-accent-contrast: #fff;    /* text on top of the accent */
  --pf-muted: ...;               /* secondary text     (default: derived from text color) */
  --pf-border: ...;              /* hairlines          (default: derived from text color) */
  --pf-surface: ...;             /* card background    (default: transparent) */
  --pf-radius: 0.375rem;         /* corner radius */
  --pf-success: ...; --pf-danger: ...; --pf-warning: ...;   /* status colors */
}

For deeper changes, override styles targeting the .pf-* classes, or replace /_content/Paymentify/paymentify.css entirely by shipping your own copy.

Billing identity: users vs. tenants

UserIdResolver returns the billing identity — an opaque string Paymentify stores as ExternalUserId on the customer record. One subscription is bought per unique value.

Per-user billing (each user pays independently):

opts.UserIdResolver = ctx => ctx.User.FindFirstValue(ClaimTypes.NameIdentifier);

Per-tenant billing (one subscription covers the whole org):

opts.UserIdResolver = ctx => ctx.User.FindFirstValue("tenant_id");
// or resolve from a scoped service:
opts.UserIdResolver = ctx =>
    ctx.RequestServices.GetRequiredService<ITenantService>().GetTenantId(ctx);

All users with the same billing identity share the same subscription. [RequireActiveSubscription] works for all of them automatically.

Gating access

using Paymentify.Auth;

[RequireActiveSubscription]
public class DashboardController : Controller { ... }

Requires UserIdResolver to be configured. Registers the "ActiveSubscription" authorization policy backed by SubscriptionService.IsActiveAsync. When PaymentsMode = Disabled, the policy always passes (so you can test gated pages without a real subscription).

OnHold/Failed subscriptions (payment declined, awaiting Dodo's retry) count as active for DunningGracePeriod after their last status change — see Configuration reference.

[RequireActiveSubscription] is boolean (any active subscription passes) — it doesn't know about plan tiers. To gate a specific feature behind a paid plan (or a particular tier), check GetActivePlanAsync directly:

var plan = await subscriptions.GetActivePlanAsync(userId);
var isPaid = plan?.ProductId is not null;   // null ProductId = free tier

If the billing identity isn't the current user — e.g. a project belongs to an organization, and the organization owner holds the subscription — resolve it first, then look up the plan:

var ownerId = await db.Projects
    .Where(p => p.Id == projectId)
    .Select(p => p.Organization.OwnerId)
    .SingleOrDefaultAsync(ct);

var plan = ownerId is not null ? await subscriptions.GetActivePlanAsync(ownerId) : null;
if (plan?.ProductId is null)
    return Results.Json(
        new { success = false, error = "This feature requires a paid plan.", code = "plan_limit" },
        statusCode: StatusCodes.Status402PaymentRequired);

In an MVC controller, use Forbid() instead of the 402 JSON response. Combine with GetLimits<T>() (above) when the gate is a quota rather than a yes/no feature.

Plan configuration

opts.Plans = [
    new()
    {
        ProductId        = null,             // null = free tier (no Dodo product)
        Name             = "Free",
        PriceDisplay     = "$0/mo",
        Description      = "Perfect for getting started",
        Features         = ["Up to 5 projects", "Basic support"],
        Limits           = new MyLimits(MaxProjects: 5),
    },
    new()
    {
        ProductId        = "prod_pro",
        Name             = "Pro",
        PriceDisplay     = "$19/mo",
        YearlyProductId  = "prod_pro_yearly",
        YearlyPriceDisplay = "$190/yr",
        Description      = "For power users",
        Highlighted      = true,             // visually emphasised on the pricing page
        Features         = ["Unlimited projects", "Priority support"],
        Limits           = new MyLimits(MaxProjects: -1),  // -1 = unlimited
        Available        = true,             // false → shows UnavailableLabel instead of buy button
        UnavailableLabel = "Coming soon",
    },
];

Plan limits (entitlements)

Attach any type to Limits and retrieve it typed via GetLimits<T>():

// Define your limits type
record MyLimits(int MaxProjects);

// Assign on plans
new PaymentifyPlan { ..., Limits = new MyLimits(5) }

// Enforce in your app
var plan = await subscriptionService.GetActivePlanAsync(userId);
var limits = plan?.GetLimits<MyLimits>();
var max = limits?.MaxProjects ?? 0;
if (max != -1 && current >= max)
    return Forbid();

GetActivePlanAsync returns the active paid plan, or the first plan with ProductId == null (free tier) if the user has no paid subscription.

Pre-monetization mode

Launch with pricing visible but checkout disabled. Collect visitor interest. Flip one flag when you're ready.

When Disabled:

• Paid plan cards show UnavailableLabel (default "Join the waitlist") with an inline email form that records interest — works without JavaScript.
• The billing page explains that billing isn't enabled yet.
• Admin pages show a banner reminding you the pricing page is interest-only.
• Checkout attempts on /paymentify/pricing show an error instead of starting a session.
• The waitlist form on /paymentify/pricing records purchase intent.
• [RequireActiveSubscription] always passes (useful for testing gated pages).
• ApiKey and WebhookSecret are not required.

opts.PaymentsMode = PaymentsMode.Disabled;

opts.Plans = [
    new() { ProductId = null,           Name = "Free",    PriceDisplay = "$0/mo" },
    new() { ProductId = "prod_starter", Name = "Starter", PriceDisplay = "$9/mo",
            Available = false, UnavailableLabel = "Join waitlist" },
];

Recording interest

POST /paymentify/interest
{ "productId": "prod_starter", "email": "user@example.com" }

Returns { "recorded": true }. Anonymous — no login required. Returns HTTP 400 if PaymentsMode != Disabled.

Captured rows are browsable at /paymentify/admin/interest (requires AdminAccessResolver), or read them back like any other table via IPaymentifyDbContext:

var waitlist = await db.PurchaseInterests
    .Where(i => i.ProductId == "prod_starter")
    .OrderByDescending(i => i.CreatedAt)
    .ToListAsync();

Going live

opts.PaymentsMode = PaymentsMode.Live;
opts.BaseUrl      = "https://live.dodopayments.com";

Remove Available = false from any plans you're ready to sell.

Configuration reference

Event handlers

Implement IPaymentifyEventHandler<TEvent> and register with DI to react to Dodo webhook events:

using Paymentify.Events;

public class MyHandler : IPaymentifyEventHandler<SubscriptionActivatedEvent>
{
    public Task HandleAsync(SubscriptionActivatedEvent e, CancellationToken ct)
    {
        // provision access, send welcome email, etc.
        return Task.CompletedTask;
    }
}

services.AddScoped<IPaymentifyEventHandler<SubscriptionActivatedEvent>, MyHandler>();

Subscription events

Reacting to any plan change

There's no single "the plan changed" event — if you want to invalidate cached, plan-dependent data (entitlements, feature flags, etc.) regardless of which subscription event caused it, implement IPaymentifyEventHandler<TEvent> for all the plan-affecting event types on one class and register it against each. WebhookProcessor resolves handlers per event type, so a class implementing multiple IPaymentifyEventHandler<T> interfaces runs for each of them:

public class PlanChangeCacheInvalidator :
    IPaymentifyEventHandler<SubscriptionActivatedEvent>,
    IPaymentifyEventHandler<SubscriptionPlanChangedEvent>,
    IPaymentifyEventHandler<SubscriptionRenewedEvent>,
    IPaymentifyEventHandler<SubscriptionCancelledEvent>,
    IPaymentifyEventHandler<SubscriptionOnHoldEvent>,
    IPaymentifyEventHandler<SubscriptionFailedEvent>,
    IPaymentifyEventHandler<SubscriptionExpiredEvent>,
    IPaymentifyEventHandler<SubscriptionUpdatedEvent>
{
    public Task HandleAsync(SubscriptionActivatedEvent e, CancellationToken ct) => Invalidate(e.ExternalUserId, ct);
    public Task HandleAsync(SubscriptionPlanChangedEvent e, CancellationToken ct) => Invalidate(e.ExternalUserId, ct);
    public Task HandleAsync(SubscriptionRenewedEvent e, CancellationToken ct) => Invalidate(e.ExternalUserId, ct);
    public Task HandleAsync(SubscriptionCancelledEvent e, CancellationToken ct) => Invalidate(e.ExternalUserId, ct);
    public Task HandleAsync(SubscriptionOnHoldEvent e, CancellationToken ct) => Invalidate(e.ExternalUserId, ct);
    public Task HandleAsync(SubscriptionFailedEvent e, CancellationToken ct) => Invalidate(e.ExternalUserId, ct);
    public Task HandleAsync(SubscriptionExpiredEvent e, CancellationToken ct) => Invalidate(e.ExternalUserId, ct);
    public Task HandleAsync(SubscriptionUpdatedEvent e, CancellationToken ct) => Invalidate(e.ExternalUserId, ct);

    private Task Invalidate(string? externalUserId, CancellationToken ct)
    {
        // e.g. cache.Remove($"plan:{externalUserId}")
        return Task.CompletedTask;
    }
}

services.AddScoped<IPaymentifyEventHandler<SubscriptionActivatedEvent>, PlanChangeCacheInvalidator>();
services.AddScoped<IPaymentifyEventHandler<SubscriptionPlanChangedEvent>, PlanChangeCacheInvalidator>();
services.AddScoped<IPaymentifyEventHandler<SubscriptionRenewedEvent>, PlanChangeCacheInvalidator>();
services.AddScoped<IPaymentifyEventHandler<SubscriptionCancelledEvent>, PlanChangeCacheInvalidator>();
services.AddScoped<IPaymentifyEventHandler<SubscriptionOnHoldEvent>, PlanChangeCacheInvalidator>();
services.AddScoped<IPaymentifyEventHandler<SubscriptionFailedEvent>, PlanChangeCacheInvalidator>();
services.AddScoped<IPaymentifyEventHandler<SubscriptionExpiredEvent>, PlanChangeCacheInvalidator>();
services.AddScoped<IPaymentifyEventHandler<SubscriptionUpdatedEvent>, PlanChangeCacheInvalidator>();

Payment events

Refund events

Dispute events

Dunning events

SubscriptionService

SubscriptionService is registered as scoped and injectable directly into your own services and controllers.

public class MyService(SubscriptionService subscriptions) { ... }

Database

Four tables, all queryable directly through IPaymentifyDbContext (or your AppDbContext) and all with unique indexes on their Dodo-issued IDs:

SubscriptionStatus (Paymentify.Domain) is Active | Cancelled | OnHold | Failed | Expired.

The library ships no migrations. The host app owns them:

dotnet ef migrations add PaymentifyInit --project YourApp --context AppDbContext
dotnet ef database update --project YourApp --context AppDbContext

Apply at startup:

using var scope = app.Services.CreateScope();
await scope.ServiceProvider.GetRequiredService<AppDbContext>().Database.MigrateAsync();

Supports Postgres and SQLite (or any EF provider your DbContext is configured with). Generate the migration against your provider — migrations are provider-specific (column types like TEXT/INTEGER vs text/boolean are baked in at scaffold time), so a SQLite-generated migration will not run cleanly on Postgres. samples/SampleApp/Migrations/* is SQLite-only reference output, not a template to copy for other providers.

Health check

A health check named "paymentify" is automatically registered. It verifies database connectivity. Wire it up with your existing health check endpoint:

app.MapHealthChecks("/health");

Pricing view component

/paymentify/pricing is the authenticated pricing page — checkout forms, waitlist, current-plan state — and redirects anonymous visitors to RegisterUrl. For a public marketing/landing page, embed PaymentifyPricingViewComponent instead: it renders static plan cards (no forms, no user context) with a single CTA per plan linking to RegisterUrl (or PricingUrl if unset):

@await Component.InvokeAsync("PaymentifyPricing")

Overriding built-in pages

Paymentify's pricing and billing pages ship as part of a Razor Class Library. ASP.NET Core gives the host app's pages priority: if you place a file at the same relative path, your version wins and the library's is ignored.

Custom look, same logic

Create Pages/Pricing.cshtml + Pages/Pricing.cshtml.cs in your host app, inheriting from the library's model:

// Pages/Pricing.cshtml.cs
using Paymentify.Pages;
using Paymentify.Options;
using Paymentify.Services;

public class PricingModel : Paymentify.Pages.PricingModel
{
    public PricingModel(SubscriptionService svc, PaymentifyOptions opts, ILogger<PricingModel> logger)
        : base(svc, opts, logger) { }

    // Add extra properties or override handlers as needed
}

@* Pages/Pricing.cshtml *@
@page "/paymentify/pricing"
@model YourApp.Pages.PricingModel

@* Your custom HTML — all base model properties and handlers are available *@

Do the same with Pages/Billing.cshtml / BillingModel for the billing page.

Custom URL

Set PricingUrl / BillingUrl in options and create pages at those paths:

opts.PricingUrl = "/pricing";
opts.BillingUrl = "/account/billing";
opts.CheckoutSuccessUrl = "/account/billing";
opts.CheckoutCancelUrl  = "/pricing";

Then create Pages/Pricing.cshtml at @page "/pricing" and Pages/Account/Billing.cshtml at @page "/account/billing". The library's built-in pages at /paymentify/pricing and /paymentify/billing remain registered but the library never redirects users there.

SuperAdmin pages

Three built-in Razor Pages, gated behind AdminAccessResolver (a Func<HttpContext, bool>, same pattern as UserIdResolver — null by default, so the pages 404 until you configure it):

opts.AdminAccessResolver = ctx => ctx.User.IsInRole("admin");

Manual subscriptions never call the Dodo API (creation or cancellation) and are invisible to webhook processing, since WebhookProcessor only ever looks up by real Dodo-issued IDs. Every status override, manual grant/cancel, and webhook retry writes a row to AdminAuditLog (who, when, what changed).