Installation

Install PayKit, create a server instance, configure env vars, and mount your first webhook handler.

This page describes the planned MVP setup. Some package names and helpers may still change before v1.

Install PayKit

pnpm add paykitjs @paykitjs/stripe

npm install paykitjs @paykitjs/stripe

bun add paykitjs @paykitjs/stripe

This is an example using Stripe, but you can install the providers you need.

Configure PayKit

paykit.ts

import { createPayKit } from "paykitjs";
import { stripe } from "@paykitjs/stripe";
import { Pool } from "pg";

export const paykit = createPayKit({
  database: new Pool({
    connectionString: process.env.DATABASE_URL!,
  }),
  providers: [
    stripe({
      secretKey: process.env.STRIPE_SECRET_KEY!,
      webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
    }),
  ],
  on: {
    "payment.succeeded": async ({ payment }) => {
      console.log("Payment received", payment);
    },
  },
});

PayKit CLI discovers paykit.ts by default, so keep your exported instance in that file.

Configure environment variables

.env

DATABASE_URL=postgres://postgres:postgres@localhost:5432/paykit

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

Set the database URL and provider credentials used by your PayKit instance.

Run PayKit migrations

npx paykitjs migrate

This applies PayKit's packaged SQL migrations and creates the paykit_* tables plus the paykit_migrations journal. PayKit does not create tables at runtime.

Add the webhook route

src/app/api/paykit/webhooks/[providerId]/route.ts

import { paykitHandler } from "paykitjs/handlers/next";

import { paykit } from "@/lib/paykit";

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

PayKit uses the provider ID in the route to select the adapter and verify the webhook signature.

Set up storage

PayKit's MVP stores billing state in Postgres using PayKit-owned tables such as:

paykit_customer
paykit_provider_customer
paykit_payment_method
paykit_payment
paykit_migrations

The migration flow is first-party and explicit: update your PayKit version, run paykitjs migrate, then start your app.