Installation

Install the package

Let's start by adding PayKit to your project:

pnpm add paykitjs

bun add paykitjs

npm install paykitjs

Create the PayKit instance

Create a file named paykit.ts anywhere in your app.

Usually you would put it somewhere in src/, src/lib/.

Import createPayKit and export your paykit instance. This is the main server entry point for all billing.

import { createPayKit } from "paykitjs";

export const paykit = createPayKit({
  // ...
});

Configure provider

PayKit can operate with different payment providers. Here's an example with Stripe, but you can easily configure another one, like Polar, Creem, and custom!

Install the provider adapter and plug it into your instance.

pnpm add @paykitjs/stripe

bun add @paykitjs/stripe

npm install @paykitjs/stripe

import { stripe } from "@paykitjs/stripe";

export const paykit = createPayKit({
  // ...
  provider: stripe({ 
    secretKey: process.env.STRIPE_SECRET_KEY!, 
    webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
  }),
});

Configure database

PayKit needs a database to store billing state, such as subscriptions. You can create a separate database, or simply plug it into the app's own db.

Pass a connection string directly, or pg.Pool.

import { Pool } from "pg";

export const paykit = createPayKit({
  // ...
  database: new Pool({
    connectionString: process.env.DATABASE_URL!,
  }),
});

Mount request handler

To handle webhooks and client API requests, you need to set up a request handler on your server.

Create a new file or route in your framework's designated catch-all route handler. This route should handle requests for the path /paykit/* (unless you've configured a different base path).

import { paykitHandler } from "paykitjs/handlers/next";
import { paykit } from "@/lib/paykit";

export const { GET, POST } = paykitHandler(paykit);

import { createFileRoute } from "@tanstack/react-router";
import { paykit } from "@/lib/paykit";

async function handle({ request }: { request: Request }) {
    return paykit.handler(request)
}

export const Route = createFileRoute("/paykit/$")({
  server: {
    handlers: {
      GET: handle,
      POST: handle,
    },
  },
});

import { paykit } from "./paykit";

// paykit.handler: (request: Request) => Promise<Response>
// Mount it on any path that catches /paykit/*
app.all("/paykit/*", (req) => paykit.handler(req));

Create client instance

The client-side library helps you interact with the server. PayKit client sdk suitable for almost all modern frameworks, including React.

import { createPayKitClient } from "paykitjs/client";
import type { paykit } from "@/server/paykit";

export const paykitClient = createPayKitClient<typeof paykit>();

To use client we also need to authenticate incoming requests on the server, to do this, add the identify option to your server instance.

export const paykit = createPayKit({
  // ...
  identify: async ({ headers }) => {
    const session = await auth.api.getSession({ headers });
    if (!session) return null;
    return {
      customerId: session.user.id,
      email: session.user.email,
      name: session.user.name,
      // Just pass user's data, and Stripe customer gets synced automatically!
    };
  },
});

Define your products

Optionally. PayKit provides a code-first way to create your plans, and a very useful usage billing with track() and report() out of the box.

By defining you products in code don't have to touch Stripe's dashboard at all. It automatically syncs your pricing with your provider, and you unlock a full type-safety with inferred ID types!

import { feature, plan } from "paykitjs";

const messages = feature({ id: "messages", type: "metered" });
const proModels = feature({ id: "pro_models", type: "boolean" });

export const free = plan({
  id: "free",
  name: "Free",
  group: "base",
  default: true,
  includes: [
    messages({ limit: 100, reset: "month" })
  ],
});

export const pro = plan({
  id: "pro",
  name: "Pro",
  group: "base",
  price: { amount: 19, interval: "month" },
  includes: [
    messages({ limit: 2000, reset: "month" }), 
    proModels()
  ],
});

Then pass your plans to the main options:

import { free, pro } from "./plans";

export const paykit = createPayKit({
  // ...
  plans: [free, pro],
});

Push changes to DB

PayKit includes a CLI tool to keep your database in sync with your configuration.

pnpm dlx paykitjs push

bunx paykitjs push

npx paykitjs push