---
id: sm-dodo-best-practices
name: "dodo-best-practices"
url: https://skills.yangsir.net/skill/sm-dodo-best-practices
author: dodopayments
domain: finance
tags: ["dodo-payments", "payment-gateway", "e-commerce-payments", "financial-transactions"]
install_count: 473
rating: 4.20 (20 reviews)
github: https://github.com/dodopayments/skills
---

# dodo-best-practices

> Dodo Payments集成指南技能，提供Dodo Payments的API参考和代码示例，帮助用户启动、扩展和管理支付。

**Stats**: 473 installs · 4.2/5 (20 reviews)

## Before / After 对比

### Dodo Payments支付集成与管理效率对比

## Readme

# dodo-best-practices

# Dodo Payments Integration Guide

**Always consult [docs.dodopayments.com](https://docs.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](https://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_low` - 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

- [Documentation](https://docs.dodopayments.com)

- [API Reference](https://docs.dodopayments.com/api-reference/introduction)

- [SDK Repositories](https://github.com/dodopayments)

- [Discord Community](https://discord.gg/bYqAp4ayYh)

- [Support](https://github.com/dodopayments/skills/blob/HEAD/dodo-payments/best-practices/mailto:support@dodopayments.com)

- [Credit-Based Billing](https://docs.dodopayments.com/features/credit-based-billing)

Weekly Installs198Repository[dodopayments/skills](https://github.com/dodopayments/skills)GitHub Stars7First SeenJan 21, 2026Security Audits[Gen Agent Trust HubPass](/dodopayments/skills/dodo-best-practices/security/agent-trust-hub)[SocketPass](/dodopayments/skills/dodo-best-practices/security/socket)[SnykWarn](/dodopayments/skills/dodo-best-practices/security/snyk)Installed onopencode162gemini-cli159codex154github-copilot147cursor130amp127

---
*Source: https://skills.yangsir.net/skill/sm-dodo-best-practices*
*Markdown mirror: https://skills.yangsir.net/api/skill/sm-dodo-best-practices/markdown*