# Dodo Payments (/docs/plugins/dodopayments)

更好的 Dodo Payments 认证插件



[Dodo Payments](https://dodopayments.com) 是一个全球商户记录平台，帮助 AI、SaaS 和数字业务在 150 多个国家销售产品，无需处理税务、欺诈或合规问题。一个简单且开发者友好的 API 支持结账、计费和付款，让您几分钟内即可全球上线。

<Callout>
  本插件由 Dodo Payments 团队维护。如有 BUG、问题或功能请求，
  请访问 [Dodo Payments GitHub 仓库](https://github.com/dodopayments/dodo-adapters)。
</Callout>

<Card href="https://discord.gg/bYqAp4ayYh" title="在 Dodo Payments 的 Discord 上获取支持">
  有问题吗？我们的团队随时可以在 Discord 上为您提供帮助。
</Card>

## 功能 [#功能]

* 自动在注册时创建客户
* 带有产品 slug 映射的类型安全结账流程
* 自助服务客户门户
* 带有签名验证的实时 Webhook 事件处理

<Card href="https://app.dodopayments.com" title="开始使用 Dodo Payments">
  您需要一个 Dodo Payments 账户和 API 密钥才能使用此集成。
</Card>

## 安装 [#安装]

<Steps>
  <Step title="安装依赖">
    在项目根目录运行以下命令：

    ```bash
    npm install @dodopayments/better-auth dodopayments better-auth zod
    ```
  </Step>

  <Step title="配置环境变量">
    将以下内容添加到您的 `.env` 文件：

    ```txt
    DODO_PAYMENTS_API_KEY=your_api_key_here
    DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
    ```
  </Step>

  <Step title="设置服务端集成">
    创建或更新 `src/lib/auth.ts`：

    ```typescript
    import { betterAuth } from "better-auth";
    import {
      dodopayments,
      checkout,
      portal,
      webhooks,
    } from "@dodopayments/better-auth";
    import DodoPayments from "dodopayments";

    export const dodoPayments = new DodoPayments({
      bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
      environment: "test_mode"
    });

    export const auth = betterAuth({
      plugins: [
        dodopayments({
          client: dodoPayments,
          createCustomerOnSignUp: true,
          use: [
            checkout({
              products: [
                {
                  productId: "pdt_xxxxxxxxxxxxxxxxxxxxx",
                  slug: "premium-plan",
                },
              ],
              successUrl: "/dashboard/success",
              authenticatedUsersOnly: true,
            }),
            portal(),
            webhooks({
              webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET!,
              onPayload: async (payload) => {
                console.log("Received webhook:", payload.event_type);
              },
            }),
          ],
        }),
      ],
    });
    ```

    <Card>
      将 `environment` 设置为 `live_mode` 即为生产环境。
    </Card>
  </Step>

  <Step title="设置客户端集成">
    创建或更新 `src/lib/auth-client.ts`：

    ```typescript
    import { createAuthClient } from "better-auth/react";
    import { dodopaymentsClient } from "@dodopayments/better-auth";

    export const authClient = createAuthClient({
      baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3000",
      plugins: [dodopaymentsClient()],
    });
    ```
  </Step>
</Steps>

## 使用 [#使用]

### 创建结账会话 [#创建结账会话]

```typescript
const { data: checkoutSession, error } =
  await authClient.dodopayments.checkoutSession({
  slug: "premium-plan",
});

if (checkoutSession) {
  window.location.href = checkoutSession.url;
}
```

<Callout type="warn">
  `authClient.dodopayments.checkout()` 已被弃用。新的集成请使用
  `authClient.dodopayments.checkoutSession()`。
</Callout>

### 访问客户门户 [#访问客户门户]

```typescript
const { data: customerPortal, error } = await authClient.dodopayments.customer.portal();
if (customerPortal && customerPortal.redirect) {
  window.location.href = customerPortal.url;
}
```

### 列出客户数据 [#列出客户数据]

```typescript
// 获取订阅
const { data: subscriptions, error } =
  await authClient.dodopayments.customer.subscriptions.list({
    query: {
      limit: 10,
      page: 1,
      active: true,
    },
  });

// 获取付款历史
const { data: payments, error } = await authClient.dodopayments.customer.payments.list({
  query: {
    limit: 10,
    page: 1,
    status: "succeeded",
  },
});
```

### Webhooks [#webhooks]

<Card>
  Webhooks 插件处理来自 Dodo Payments 的实时支付事件，具备安全的签名验证。默认端点为 `/api/auth/dodopayments/webhooks`。
</Card>

<Steps>
  <Step title="生成并设置 Webhook 密钥">
    在 Dodo Payments 控制台中为您的端点 URL（例如 `https://your-domain.com/api/auth/dodopayments/webhooks`）生成 Webhook 密钥，并将其设置到 `.env` 文件中：

    ```txt
    DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
    ```
  </Step>

  <Step title="处理 Webhook 事件">
    示例处理程序：

    ```typescript
    webhooks({
      webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_SECRET!,
      onPayload: async (payload) => {
        console.log("Received webhook:", payload.event_type);
      },
    });
    ```
  </Step>
</Steps>

## 配置参考 [#配置参考]

### 插件选项 [#插件选项]

* **client**（必需）：DodoPayments 客户端实例
* **createCustomerOnSignUp**（可选）：在用户注册时自动创建客户
* **use**（必需）：要启用的插件数组（checkout、portal、webhooks）

### 结账插件选项 [#结账插件选项]

* **products**：产品数组或返回产品的异步函数
* **successUrl**：支付成功后重定向的 URL
* **authenticatedUsersOnly**：要求用户认证（默认：false）

如果遇到任何问题，请参考 [Dodo Payments 文档](https://docs.dodopayments.com) 进行排查。