프레임워크 어댑터 개요

프레임워크 어댑터를 사용하면 각 프레임워크의 request 및 response types를 활용하여 앱에 Dodo Payments checkout, Customer Portal 및 webhook handler를 추가할 수 있습니다. 각 어댑터는 @dodopayments scope의 npm package입니다. 이 package는 checkout validation, Dodo Payments API requests, webhook payload validation 및 typed event callbacks에 @dodopayments/core를 사용합니다.

각 어댑터는 handler configuration에서 API key와 environment를 받습니다. 이러한 값은 environment variables에 저장하고 handler를 생성할 때 전달하세요.

코딩 에이전트가 대신 어댑터를 추가하도록 하려면 Agent Plugin을 설치하세요.

사용 가능한 프레임워크 어댑터

사용 중인 프레임워크에 맞는 어댑터를 선택하세요:

Next.js

App Router에서 checkout, customer portal 및 webhook을 처리하는 route handler입니다.

Nuxt

full-stack Vue framework인 Nuxt 3를 위한 server route handler입니다.

Express

Node.js 앱에서 Express 5 route를 처리하는 request handler입니다.

Fastify

plugin architecture를 사용하는 Node.js framework인 Fastify 5를 위한 route handler입니다.

Hono

Cloudflare Workers, 기타 edge runtime 및 Node.js를 위한 web framework인 Hono 4의 route handler입니다.

Astro

content-focused web framework인 Astro 4 및 5를 위한 server endpoint handler입니다.

SvelteKit

full-stack Svelte framework인 SvelteKit 2를 위한 server route handler입니다.

Remix

full-stack React framework인 Remix 2를 위한 loader 및 action handler입니다.

TanStack Start

type-safe full-stack React framework인 TanStack Start를 위한 server route handler입니다.

Better Auth

checkout, portal, usage 및 webhook endpoint를 추가하는 Better Auth authentication framework용 plugin이며, sign-up 시 customer를 생성할 수 있습니다.

Convex

checkout 및 customer portal action과 webhook HTTP action을 제공하는 Convex backend용 component입니다.

Bun

checkout, customer portal 및 webhook을 위한 native Bun.serve() handler입니다.

핵심 기능

route handler 어댑터는 다음 기능을 공유합니다:

기능	설명
Checkout Handler	Static, dynamic 및 checkout session flow
Customer Portal	고객이 subscription 및 billing detail을 관리할 수 있는 Customer Portal을 여는 handler
Webhook Handler	개별 event type에 대한 signature verification 및 typed callback
Environment Config	typed handler option을 통해 전달되는 API credential 및 environment
Type Safety	handler option 및 webhook payload를 위한 TypeScript type

Better Auth plugin과 Convex component는 각자의 API를 통해 동일한 기능을 제공합니다. 차이점은 각 페이지를 참조하세요.

빠른 시작

세 단계로 route handler 어댑터를 설정하세요.

Install the Adaptor

프레임워크에 맞는 package를 설치하세요:

npm install @dodopayments/nextjs

npm install @dodopayments/nuxt

npm install @dodopayments/express

npm install @dodopayments/hono

npm install @dodopayments/astro

npm install @dodopayments/sveltekit

Configure Environment Variables

환경에 Dodo Payments credential을 추가하세요. dashboard의 Developer → API Keys에서 API key를, Developer → Webhooks에서 webhook secret을 생성하세요. test mode API key는 test_mode에서만 작동합니다.

DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
DODO_PAYMENTS_ENVIRONMENT="test_mode" # or "live_mode"

environment를 전달하지 않으면 어댑터는 live_mode를 사용합니다.

.env file 또는 secret을 version control에 절대 commit하지 마세요.

Create Route Handlers

checkout route를 생성하세요. customer portal 및 webhook route도 같은 패턴을 따릅니다:

Next.js
Express
Hono

// app/checkout/route.ts
import { Checkout } from "@dodopayments/nextjs";

export const GET = Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
});

import express from 'express';
import { checkoutHandler } from '@dodopayments/express';

const app = express();

app.get('/api/checkout', checkoutHandler({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
}));

import { Hono } from "hono";
import { Checkout } from "@dodopayments/hono";

const app = new Hono();

app.get('/checkout', Checkout({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
  environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
}));

이제 checkout route가 checkout URL을 반환합니다. 각 어댑터 페이지에서는 customer portal 및 webhook handler를 설명하고 모든 option을 나열합니다.

Checkout Flow Type

route handler 어댑터는 세 가지 checkout flow type을 지원합니다. Better Auth plugin은 checkout session과 deprecated dynamic checkout을 지원합니다. Convex component는 checkout session만 지원합니다.

Static Checkout (GET)

Static checkout은 하나의 product에 대한 payment link를 반환하므로 이를 공유하거나 redirect할 수 있습니다. query parameter로 product ID를 전달하세요:

/api/checkout?productId=pdt_xxx&quantity=1

handler는 product가 존재하는지 확인하고 link를 checkout_url로 반환합니다. 선택적 query parameter를 사용하면 customer detail을 미리 입력하고 checkout form을 제어할 수 있습니다.

Dynamic Checkout (POST)

Dynamic checkout은 사용자 지정 detail이 포함된 JSON body에서 payment link를 생성합니다. billing 및 customer가 필요합니다:

{
  "product_id": "pdt_xxx",
  "quantity": 1,
  "billing": {
    "city": "San Francisco",
    "country": "US",
    "state": "CA",
    "street": "123 Main St",
    "zipcode": "94102"
  },
  "customer": {
    "email": "customer@example.com",
    "name": "John Doe"
  }
}

one-time payment와 subscription을 모두 지원합니다. product type에 따라 deprecated POST /payments 또는 POST /subscriptions endpoint를 호출하므로, 새로운 통합에는 checkout session을 사용하세요.

Checkout Sessions (POST)

Checkout session은 권장되는 flow입니다. 가장 많은 option을 제공하며 여러 product가 포함된 cart를 허용합니다:

{
  "product_cart": [
    { "product_id": "pdt_xxx", "quantity": 1 },
    { "product_id": "pdt_yyy", "quantity": 2 }
  ],
  "customer": {
    "email": "customer@example.com"
  }
}

지원되는 모든 field는 Checkout Sessions Guide를 참조하세요.

Webhook Event 처리

모든 route handler 어댑터는 Webhooks handler를 export합니다. 이 handler는 webhook secret과 개별 event type을 위한 선택적 typed callback을 받습니다. onPayload는 모든 event에서 실행됩니다:

Webhooks({
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY!,
  onPayload: async (payload) => {
    // Handle any webhook event
  },
  onPaymentSucceeded: async (payload) => {
    // Handle successful payments
  },
  onSubscriptionActive: async (payload) => {
    // Handle new subscriptions
  },
  // ...more than 40 optional event callbacks in total
});

callback은 payment, refund, dispute, subscription, license key, abandoned checkout, dunning, credit, entitlement grant 및 payout event를 처리합니다. Better Auth plugin은 webhooks()에서 동일한 callback을 받고, Convex component는 createDodoWebhookHandler에서 이를 받습니다.

각 webhook handler는 Standard Webhooks library를 사용하여 webhook-id, webhook-signature 및 webhook-timestamp header를 verify한 다음 Zod schema로 payload를 validate합니다. 잘못된 request는 callback이 실행되기 전에 error status와 함께 거부됩니다.

적합한 어댑터 선택

Framework	적합한 용도	Runtime
Next.js	App Router를 사용하는 full-stack React 앱	Node.js, Edge
Nuxt	Full-stack Vue.js 애플리케이션	Node.js
Express	REST API 및 기존 Node.js 앱	Node.js
Fastify	고성능 API	Node.js
Hono	Edge deployment, Cloudflare Workers	Edge, Node.js
Astro	server endpoint를 사용하는 content site	Node.js, Edge
SvelteKit	Full-stack Svelte 애플리케이션	Node.js
Remix	nested routing을 사용하는 full-stack React	Node.js
TanStack Start	Type-safe full-stack React	Node.js
Better Auth	이미 Better Auth를 사용하는 앱	Various
Convex	backend에 Convex를 사용하는 앱	Convex Runtime
Bun	Native Bun server 애플리케이션	Bun

도움말

framework adaptor에 대한 도움이 필요한 경우:

Discord: 커뮤니티 서버에서 질문하세요.
이메일: support@dodopayments.com으로 문의하세요.
GitHub: 모든 adaptor가 포함된 dodo-adapters repository에 이슈를 등록하세요.
문서: API reference를 참조하세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

사용 가능한 프레임워크 어댑터

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

핵심 기능

빠른 시작

Checkout Flow Type

Webhook Event 처리

적합한 어댑터 선택

도움말

​사용 가능한 프레임워크 어댑터

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

​핵심 기능

​빠른 시작

​Checkout Flow Type

​Webhook Event 처리

​적합한 어댑터 선택

​도움말

사용 가능한 프레임워크 어댑터

핵심 기능

빠른 시작

Checkout Flow Type

Webhook Event 처리

적합한 어댑터 선택

도움말