Stripe 와 함께 결제 기능을 구현하는 데 도움을 주는 관점 (opinionated) 라이브러리를 소개합니다.

• 코드로 플랜을 정의하여 스프라이트 계정에 동기화
• 수동 웹훅 설정 불필요 – 라이브러리가 웹훅을 처리하고 스프라이트 데이터를 DB 에 동기화
• 구독, 크레딧, 지갑 잔액, 충전, 사용량 기반 청구에 대한 간단한 API
• 좌석 기반 청구, 세금 징수, 플랜 업그레이드 및 다운그레이드 (크레딧의 합리적인 처리 포함) 지원
• 커스텀 로직을 위한 선택적 콜백 (onSubscriptionCreated 등)

이 가이드는 Next.js 앱과 PostgreSQL 데이터베이스를 가지고 있다고 가정합니다. test mode 의 Stripe API 키로 시작하는 것을 권장하여 개발 환경에서 로컬 테스트할 수 있습니다. 그런 다음, 이 가이드는 앱을 프로덕션에 설정하는 방법을 안내합니다.

npm install stripe-no-webhooks stripe
npx stripe-no-webhooks init

다음과 같은 것이 표시됩니다:

Stripe test key(예: sk_test_...) – 스프라이트 대시보드에서 가져오세요.Database URL– PostgreSQL 연결 문자열 (예: postgresql://postgres:password@localhost:5432/app_db)

Site URL– 예를 들어, http://localhost:3000

로컬 개발용

이것은 .env 파일을 업데이트하고 다음 파일들을 생성합니다:

billing.config.ts: 플랜을 가진 설정 파일

lib/billing.ts: 코어 청구 클라이언트 인스턴스

app/api/stripe/[...all]/route.ts: 웹훅 핸들러 및 API 라우터

npx stripe-no-webhooks migrate

이것은 스프라이트 데이터를 동기화하고 크레딧 및 사용량을 추적하기 위한 필요한 테이블을 가진 stripe 스키마를 데이터베이스에 생성합니다.

billing.config.ts 를 편집하여 테스트 환경용 플랜을 정의합니다. 여기에는 예시가 있습니다:

const billingConfig: BillingConfig = {
test: {
plans: [
...

플랜은 크레딧, 지갑 및 사용량 기반 청구도 포함할 수 있습니다:

{
name: "Pro",
price: [{ amount: 2000, currency: "usd", interval: "month" }],
...

세부사항은 크레딧, 지갑 및 사용량 청구 문서를 참조하세요.

npx stripe-no-webhooks sync

이것은 스프라이트에서 제품/가격을 생성하고 ID 를 설정 파일에 업데이트합니다.

lib/billing.ts 를 편집하여 resolveUser 함수에서 userId 를 어떻게 가져올지 지정합니다. 예를 들어, Clerk 와 함께:

import { Billing } from "stripe-no-webhooks";
import { auth } from "@clerk/nextjs/server"; // 또는 당신의 인증
import billingConfig from "../billing.config";
...

Next.js 앱을 시작하고, 다른 터미널에서 스프라이트 웹훅을 포워딩합니다:

stripe listen --forward-to localhost:3000/api/stripe/webhook

설정이 완료되었습니다! 이제 사용하세요.

stripe-no-webhooks 는 플랜 선택, 월간/연간 토글 및 체크아웃 흐름이 내장된 전체 가격 페이지를 생성할 수 있게 합니다. 또는 checkout() 을 직접 호출할 수도 있습니다:

import { checkout } from "stripe-no-webhooks/client";
<button onClick={() => checkout({ planName: "Pro", interval: "month" })}>
Upgrade to Pro
...

테스트 카드: 4242 4242 4242 4242, 향후 MM/YY 만기, 임의의 CVC.

import { billing } from "@/lib/billing";
const subscription = await billing.subscriptions.get({ userId });
if (subscription?.status === "active") {
...

사용자가 체크아웃을 완료할 때:

• 스프라이트는 웹훅을 앱에 전송합니다.
• 라이브러리는 이를 수신하고 데이터를 데이터베이스에 동기화합니다. 크레딧/지갑이 활성화되면 잔액도 업데이트됩니다.
  billing.subscriptions.get({ userId })

Stripe 데이터에 동기화된 데이터를 기반으로 구독을 반환합니다. 크레딧 (Credits) / 지갑은 라이브러리의 내부 API 를 통해 신용 잔고와 거래 내역을 통해 자동으로 추적됩니다. 이 API 들은 모두 Idempotent(중복 실행 방지) 하므로, 중복 계산이나 누락된 거래에 대해 걱정할 필요가 없습니다.

이를 확인하려면 데이터베이스의 stripe.subscriptions 와 stripe.credit_balances 및 stripe.credit_ledger 를 확인하세요.

// 크레딧: 포함된 단위를 사용
if (await billing.credits.hasCredits({ userId, key: "api_calls", amount: 1 })) {
await billing.credits.consume({ userId, key: "api_calls", amount: 1 });
...

Credits, Wallet, 그리고 Usage 문서에서 전체 기능 세트를 확인하세요.

사용자가 구독을 관리할 수 있도록 합니다:

import { customerPortal } from "stripe-no-webhooks/client";
<button onClick={() => customerPortal()}>
Manage Billing
...

export const billing = new Billing({
billingConfig,
callbacks: {
...

npx stripe-no-webhooks generate pricing-page

이 명령어는 components/PricingPage.tsx 에 완전히 커스터마이징 가능한 가격 페이지 컴포넌트를 생성합니다.

// 가격 페이지에서, 예를 들어 /pricing
import { PricingPage } from "@/components/PricingPage";
export default function Pricing() {
...

자동으로 처리: 플랜 조회, 현재 구독 감지, 월별/연간 토글, 체크아웃 흐름, 리디렉션 처리, 오류 처리 등.

• billing.config.ts 의 production 섹션에 플랜 추가

• npx stripe-no-webhooks sync 실행하고 "Set up for production" 선택. 이는 다음을 수행합니다:

  • 플랜을 Stripe 라이브 모드에 동기화
  • 앱의 웹훅 엔드포인트를 Stripe 에서 생성
  • CLI 출력에서 웹훅 URL 과 비밀을 표시

• 웹훅 비밀을 프로덕션 환경 (예: Vercel 환경 변수) 에 추가:
  STRIPE_WEBHOOK_SECRET=whsec_... STRIPE_SECRET_KEY=sk_live_... # IMPORTANT: Your live Stripe secret key DATABASE_URL=postgresql://[username]:[password]@[production-db-url]:5432/[production-db-name] NEXT_PUBLIC_APP_URL=https://your-production-app.com

완전한 API 는 docs/reference.md 를 참조하세요.

LLM 이라면, 전체 문서가 https://github.com/pretzelai/stripe-no-webhooks/blob/main/docs/llms.txt 에 있습니다.