Dodo Payments 集成指南：SaaS与AI产品支付、订阅、计费一体化解决方案

dodo-best-practices by dodopayments/skills

248 周安装量

7 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/dodopayments/skills --skill dodo-best-practices

SaaS 金融科技 API

🇨🇳中文介绍

Dodo Payments 集成指南

请始终查阅 docs.dodopayments.com 以获取最新的 API 参考和代码示例。

Dodo Payments 是一款用于全球发布、扩展和变现的一体化引擎。专为 SaaS 和 AI 产品设计，它无需额外工程即可处理支付、计费、订阅和分发。

快速参考

环境变量

DODO_PAYMENTS_API_KEY - 来自仪表板的 API 密钥
DODO_PAYMENTS_WEBHOOK_SECRET - 用于验证的 Webhook 签名密钥

API 环境

生产模式 : https://api.dodopayments.com (默认)
测试模式 : https://api.dodopayments.com 并设置 environment: 'test_mode'

仪表板 URL

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

TypeScript/JavaScript

npm install dodopayments
# 或
yarn add dodopayments
# 或
pnpm add dodopayments

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode', // 或 'test_mode'
});

pip install dodopayments

from dodopayments import DodoPayments

client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])

go get github.com/dodopayments/dodopayments-go

import "github.com/dodopayments/dodopayments-go"

client := dodopayments.NewClient(
    option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
)

composer require dodopayments/client

use Dodopayments\Client;

$client = new Client(bearerToken: getenv('DODO_PAYMENTS_API_KEY'));

产品是您销售的商品。在仪表板中或通过 API 创建它们：

一次性 : 单次购买产品
订阅 : 周期性计费产品
用量计费 : 按消耗量计费的产品

信用额度是附加在产品上的虚拟余额（API 调用次数、令牌数、计算小时数）。在仪表板 → 产品 → 信用额度中创建：

自定义单位 : 您自己的指标，可配置精度
法币信用额度 : 真实货币价值（美元、欧元等）
每个产品最多可附加 3 个信用额度
可为每个额度配置结转、超额和过期规则

收取付款的主要方式。创建一个结账会话并重定向客户：

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_xxxxx', quantity: 1 }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
  },
  return_url: 'https://yoursite.com/success',
});

// 将客户重定向至：session.checkout_url

监听事件以获取实时更新：

payment.succeeded - 支付完成
payment.failed - 支付失败
subscription.active - 订阅激活
subscription.cancelled - 订阅取消
refund.succeeded - 退款处理完成
dispute.opened - 收到争议
license_key.created - 许可证密钥已生成
credit.added - 向客户授予信用额度
credit.deducted - 信用额度被消耗
credit.balance_low - 信用额度余额低于阈值

一次性支付流程

在仪表板中创建产品
使用产品 ID 创建结账会话
将客户重定向至结账 URL
处理 payment.succeeded webhook
履行订单 / 授予访问权限

// 为一次性支付创建结账
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_one_time_product', quantity: 1 }],
  customer: { email: 'customer@example.com' },
  return_url: 'https://yoursite.com/success',
});

在仪表板中创建订阅产品
创建结账会话
处理 subscription.active webhook 以授予访问权限
处理 subscription.cancelled webhook 以撤销访问权限

// 为订阅创建结账
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly_subscription', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }, // 可选试用期
  customer: { email: 'customer@example.com' },
  return_url: 'https://yoursite.com/success',
});

始终验证 Webhook 签名：

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

导航至仪表板 → 开发者 → API
点击"创建 API 密钥"
复制并安全存储密钥

切勿在客户端代码中暴露 API 密钥
使用环境变量
定期轮换密钥
开发时使用测试模式密钥

允许客户管理其订阅：

const portal = await client.customers.createPortalSession({
  customer_id: 'cust_xxxxx',
  return_url: 'https://yoursite.com/account',
});

// 重定向至：portal.url

优雅地处理 API 错误：

try {
  const session = await client.checkoutSessions.create({...});
} catch (error) {
  if (error.status === 400) {
    // 无效请求 - 检查参数
  } else if (error.status === 401) {
    // 无效的 API 密钥
  } else if (error.status === 429) {
    // 速率限制 - 实现退避策略
  }
}

使用测试 API 密钥（以 sk_test_ 开头）
使用仪表板工具测试 Webhooks
使用测试卡号：
- 4242 4242 4242 4242 - 成功
- 4000 0000 0000 0002 - 拒绝

使用 ngrok 或类似工具进行 Webhook 测试：

然后在仪表板中将 ngrok URL 配置为您的 Webhook 端点。

使用 API 路由进行服务器端操作：

// app/api/checkout/route.ts
import { NextResponse } from 'next/server';
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
});

export async function POST(req: Request) {
  const { productId, email } = await req.json();
  
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    customer: { email },
    return_url: `${process.env.NEXT_PUBLIC_URL}/success`,
  });

  return NextResponse.json({ url: session.checkout_url });
}

import express from 'express';
import DodoPayments from 'dodopayments';

const app = express();
const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY! });

app.post('/create-checkout', async (req, res) => {
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: req.body.productId, quantity: 1 }],
    customer: { email: req.body.email },
    return_url: 'https://yoursite.com/success',
  });
  res.json({ url: session.checkout_url });
});

🇺🇸English

Dodo Payments Integration Guide

Always consultdocs.dodopayments.com for the latest API reference and code examples.

Dodo Payments is the all-in-one engine to launch, scale, and monetize worldwide. Designed for SaaS and AI products, it handles payments, billing, subscriptions, and distribution without extra engineering.

Quick Reference

Environment Variables

DODO_PAYMENTS_API_KEY - Your API key from the dashboard
DODO_PAYMENTS_WEBHOOK_SECRET - Webhook signing secret for verification

API Environments

Live Mode : https://api.dodopayments.com (default)
Test Mode : https://api.dodopayments.com with environment: 'test_mode'

Dashboard URLs

Main Dashboard : app.dodopayments.com
API Keys : Dashboard → Developer → API
Webhooks : Dashboard → Developer → Webhooks
Products : Dashboard → Products

SDK Installation

TypeScript/JavaScript

npm install dodopayments
# or
yarn add dodopayments
# or
pnpm add dodopayments



import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode', // or 'test_mode'
});

Python

pip install dodopayments



from dodopayments import DodoPayments

client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])

Go

go get github.com/dodopayments/dodopayments-go



import "github.com/dodopayments/dodopayments-go"

client := dodopayments.NewClient(
    option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")),
)

PHP

composer require dodopayments/client



use Dodopayments\Client;

$client = new Client(bearerToken: getenv('DODO_PAYMENTS_API_KEY'));

Core Concepts

Products

Products are the items you sell. Create them in the dashboard or via API:

One-time : Single purchase products
Subscription : Recurring billing products
Usage-based : Metered billing per consumption

Credit Entitlements

Credits are virtual balances (API calls, tokens, compute hours) attached to products. Create them in Dashboard → Products → Credits:

Custom Unit : Your own metric with configurable precision
Fiat Credits : Real currency value (USD, EUR, etc.)
Attach up to 3 credits per product
Configure rollover, overage, and expiration per entitlement

Checkout Sessions

The primary way to collect payments. Create a checkout session and redirect customers:

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'prod_xxxxx', quantity: 1 }
  ],
  customer: {
    email: 'customer@example.com',
    name: 'John Doe',
  },
  return_url: 'https://yoursite.com/success',
});

// Redirect customer to: session.checkout_url

Webhooks

Listen to events for real-time updates:

payment.succeeded - Payment completed
payment.failed - Payment failed
subscription.active - Subscription activated
subscription.cancelled - Subscription cancelled
refund.succeeded - Refund processed
dispute.opened - Dispute received
license_key.created - License key generated
credit.added - Credits granted to customer
credit.deducted - Credits consumed
- Credit balance below threshold

Common Integration Patterns

One-Time Payment Flow

Create product in dashboard
Create checkout session with product ID
Redirect customer to checkout URL
Handle payment.succeeded webhook
Fulfill order / grant access

// Create checkout for one-time payment

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_one_time_product', quantity: 1 }],
  customer: { email: 'customer@example.com' },
  return_url: 'https://yoursite.com/success',
});

Subscription Flow

Create subscription product in dashboard
Create checkout session
Handle subscription.active webhook to grant access
Handle subscription.cancelled to revoke access

// Create checkout for subscription

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'prod_monthly_subscription', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }, // Optional trial
  customer: { email: 'customer@example.com' },
  return_url: 'https://yoursite.com/success',
});

Webhook Verification

Always verify webhook signatures:

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

API Key Management

Generation

Navigate to Dashboard → Developer → API
Click "Create API Key"
Copy and securely store the key

Security Best Practices

Never expose API keys in client-side code
Use environment variables
Rotate keys periodically
Use test mode keys for development

Customer Portal

Allow customers to manage their subscriptions:

const portal = await client.customers.createPortalSession({
  customer_id: 'cust_xxxxx',
  return_url: 'https://yoursite.com/account',
});

// Redirect to: portal.url

Error Handling

Handle API errors gracefully:

try {
  const session = await client.checkoutSessions.create({...});
} catch (error) {
  if (error.status === 400) {
    // Invalid request - check parameters
  } else if (error.status === 401) {
    // Invalid API key
  } else if (error.status === 429) {
    // Rate limited - implement backoff
  }
}

Testing

Test Mode

Use test API keys (start with sk_test_)
Test webhooks with dashboard tools
Use test card numbers:
- 4242 4242 4242 4242 - Success
- 4000 0000 0000 0002 - Decline

Local Development

Use ngrok or similar for webhook testing:

ngrok http 3000

Then configure the ngrok URL as your webhook endpoint in the dashboard.

Framework Integration

Next.js

Use API routes for server-side operations:

// app/api/checkout/route.ts
import { NextResponse } from 'next/server';
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
});

export async function POST(req: Request) {
  const { productId, email } = await req.json();
  
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: productId, quantity: 1 }],
    customer: { email },
    return_url: `${process.env.NEXT_PUBLIC_URL}/success`,
  });

  return NextResponse.json({ url: session.checkout_url });
}

Express.js

import express from 'express';
import DodoPayments from 'dodopayments';

const app = express();
const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY! });

app.post('/create-checkout', async (req, res) => {
  const session = await client.checkoutSessions.create({
    product_cart: [{ product_id: req.body.productId, quantity: 1 }],
    customer: { email: req.body.email },
    return_url: 'https://yoursite.com/success',
  });
  res.json({ url: session.checkout_url });
});

Resources

Weekly Installs

214

Repository

dodopayments/skills

GitHub Stars

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

opencode178

gemini-cli175

codex170

github-copilot163

cursor146

amp143

Lark Drive API 使用指南：飞书云文档、Wiki、表格 Token 处理与文件管理

23,400 周安装

credit.balance_low

Dodo Payments 集成指南：SaaS与AI产品支付、订阅、计费一体化解决方案

🇨🇳中文介绍

Dodo Payments 集成指南

快速参考

环境变量

API 环境

仪表板 URL

相关 Skills

SDK 安装

TypeScript/JavaScript

Python

Go

PHP

核心概念

产品

信用额度

结账会话

Webhooks

常见集成模式

一次性支付流程

订阅流程

Webhook 验证

API 密钥管理

生成

安全最佳实践

客户门户

错误处理

测试

测试模式

本地开发

框架集成

Next.js

Express.js

资源

🇺🇸English

Dodo Payments Integration Guide

Quick Reference

Environment Variables

API Environments

Dashboard URLs

SDK Installation

TypeScript/JavaScript

Python

Go

PHP

Core Concepts

Products

Credit Entitlements

Checkout Sessions

Webhooks

Common Integration Patterns

One-Time Payment Flow

Subscription Flow

Webhook Verification

API Key Management

Generation

Security Best Practices

Customer Portal

Error Handling

Testing

Test Mode

Local Development

Framework Integration

Next.js

Express.js

Resources

最新 Skills