Tổng quan về các bộ chuyển đổi Framework

Các bộ chuyển đổi framework thêm checkout, Customer Portal và webhook handlers của Dodo Payments vào ứng dụng của bạn bằng cách sử dụng các kiểu request và response của framework. Mỗi bộ chuyển đổi là một npm package trong scope @dodopayments. Các package sử dụng @dodopayments/core để xác thực checkout, thực hiện các request đến Dodo Payments API, xác thực webhook payload và cung cấp typed event callbacks.

Mỗi bộ chuyển đổi nhận API key và environment của bạn trong cấu hình handler. Lưu các giá trị này trong environment variables và truyền chúng khi tạo handler.

Để coding agent thêm bộ chuyển đổi cho bạn, hãy cài đặt Agent Plugin.

Các bộ chuyển đổi framework hiện có

Chọn bộ chuyển đổi phù hợp với framework của bạn:

Next.js

Route handlers cho checkout, customer portal và webhooks trong App Router.

Nuxt

Server route handlers cho Nuxt 3, một full-stack Vue framework.

Express

Request handlers cho Express 5 routes trong các ứng dụng Node.js.

Fastify

Route handlers cho Fastify 5, một Node.js framework có kiến trúc plugin.

Hono

Route handlers cho Hono 4, một web framework dành cho Cloudflare Workers, các edge runtime khác và Node.js.

Astro

Server endpoint handlers cho Astro 4 và 5, một web framework tập trung vào content.

SvelteKit

Server route handlers cho SvelteKit 2, một full-stack Svelte framework.

Remix

Loader và action handlers cho Remix 2, một full-stack React framework.

TanStack Start

Server route handlers cho TanStack Start, một full-stack React framework type-safe.

Better Auth

Một plugin cho Better Auth authentication framework, bổ sung các checkout, portal, usage và webhook endpoints, đồng thời có thể tạo customer khi đăng ký.

Convex

Một component cho Convex backend với các checkout và customer portal actions cùng một webhook HTTP action.

Bun

Native Bun.serve() handlers cho checkout, customer portal và webhooks.

Tính năng cốt lõi

Các route handler adaptors có chung những khả năng sau:

Tính năng	Mô tả
Checkout Handler	Các flow static, dynamic và checkout session
Customer Portal	Một handler mở Customer Portal, nơi customers quản lý subscriptions và billing details
Webhook Handler	Xác minh signature và typed callbacks cho từng event type
Environment Config	API credentials và environment được truyền qua typed handler options
Type Safety	TypeScript types cho handler options và webhook payloads

Better Auth plugin và Convex component cung cấp các khả năng tương tự thông qua API riêng của chúng. Xem trang tương ứng để biết điểm khác biệt.

Bắt đầu nhanh

Thiết lập route handler adaptor trong ba bước.

Install the Adaptor

Cài đặt package cho framework của bạn:

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

Thêm credentials của Dodo Payments vào environment. Tạo API key trong Developer → API Keys và webhook secret trong Developer → Webhooks trên dashboard. Test mode API key chỉ hoạt động với 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"

Nếu không truyền environment, adaptor sẽ sử dụng live_mode.

Không commit file .env hoặc secrets vào version control.

Create Route Handlers

Tạo checkout route. Customer portal và webhook routes tuân theo cùng một pattern:

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 của bạn hiện trả về checkout URL. Trang của mỗi adaptor trình bày customer portal và webhook handlers, đồng thời liệt kê mọi option.

Các loại Checkout Flow

Các route handler adaptors hỗ trợ ba loại checkout flow. Better Auth plugin hỗ trợ checkout sessions và dynamic checkout đã deprecated. Convex component chỉ hỗ trợ checkout sessions.

Static Checkout (GET)

Static checkout trả về payment link cho một product, vì vậy bạn có thể chia sẻ hoặc redirect đến link đó. Truyền product ID dưới dạng query parameter:

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

Handler kiểm tra product có tồn tại hay không và trả về link dưới dạng checkout_url. Các query parameters tùy chọn sẽ điền trước thông tin customer và kiểm soát checkout form.

Dynamic Checkout (POST)

Dynamic checkout tạo payment link từ JSON body với các details tùy chỉnh. billing và customer là bắt buộc:

{
  "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"
  }
}

Tính năng này hỗ trợ cả one-time payments và subscriptions. Tính năng gọi deprecated POST /payments hoặc POST /subscriptions endpoint, tùy thuộc vào product type, vì vậy hãy sử dụng checkout sessions cho các integration mới.

Checkout Sessions (POST)

Checkout sessions là flow được khuyến nghị. Flow này cung cấp nhiều option nhất và chấp nhận cart có nhiều products:

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

Để xem tất cả supported fields, hãy tham khảo Checkout Sessions Guide.

Xử lý Webhook Event

Mỗi route handler adaptor export một Webhooks handler. Handler này nhận webhook secret và các typed callbacks tùy chọn cho từng event type. onPayload chạy cho mọi 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
});

Các callbacks bao quát các event về payment, refund, dispute, subscription, license key, abandoned checkout, dunning, credit, entitlement grant và payout. Better Auth plugin nhận các callbacks tương tự trong webhooks(), còn Convex component nhận chúng trong createDodoWebhookHandler.

Mỗi webhook handler xác minh các headers webhook-id, webhook-signature và webhook-timestamp bằng Standard Webhooks library, sau đó xác thực payload bằng Zod schemas. Các request không hợp lệ sẽ bị từ chối với error status trước khi callbacks của bạn chạy.

Chọn Adaptor phù hợp

Framework	Phù hợp nhất cho	Runtime
Next.js	Ứng dụng React full-stack với App Router	Node.js, Edge
Nuxt	Ứng dụng Vue.js full-stack	Node.js
Express	REST APIs và các ứng dụng Node.js truyền thống	Node.js
Fastify	APIs hiệu năng cao	Node.js
Hono	Edge deployments, Cloudflare Workers	Edge, Node.js
Astro	Content sites với server endpoints	Node.js, Edge
SvelteKit	Ứng dụng Svelte full-stack	Node.js
Remix	React full-stack với nested routing	Node.js
TanStack Start	React full-stack type-safe	Node.js
Better Auth	Các ứng dụng đã sử dụng Better Auth	Various
Convex	Các ứng dụng sử dụng Convex cho backend	Convex Runtime
Bun	Các ứng dụng Bun server native	Bun

Nhận trợ giúp

Để được trợ giúp về framework adaptor:

Discord: Đặt câu hỏi trong máy chủ cộng đồng.
Email: Liên hệ support@dodopayments.com.
GitHub: Mở một issue trong repository dodo-adapters, nơi lưu trữ mọi adaptor.
Tài liệu: Xem tài liệu tham khảo API.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Tổng quan về các bộ chuyển đổi Framework

Các bộ chuyển đổi framework hiện có

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

Tính năng cốt lõi

Bắt đầu nhanh

Các loại Checkout Flow

Xử lý Webhook Event

Chọn Adaptor phù hợp

Nhận trợ giúp

​Các bộ chuyển đổi framework hiện có

Next.js

Nuxt

Express

Fastify

Hono

Astro

SvelteKit

Remix

TanStack Start

Better Auth

Convex

Bun

​Tính năng cốt lõi

​Bắt đầu nhanh

​Các loại Checkout Flow

​Xử lý Webhook Event

​Chọn Adaptor phù hợp

​Nhận trợ giúp

Các bộ chuyển đổi framework hiện có

Tính năng cốt lõi

Bắt đầu nhanh

Các loại Checkout Flow

Xử lý Webhook Event

Chọn Adaptor phù hợp

Nhận trợ giúp