dodo-payments
Integrates Dodo Payments with the dodopayments SDK and the Dodo Payments MCP server. Covers checkout sessions, subscriptions and plan changes, webhook signature verification, usage-based (metered) billing, credits, license keys, products, discounts, localized pricing, customers and the customer portal, refunds and disputes, framework adapters, Better Auth, BillingSDK, mobile checkout, and test mode through go-live. Use whenever a task mentions Dodo Payments, dodopayments, a checkout or pay button, a subscription, a webhook from Dodo, metered or usage billing, credits, license keys, refunds, or a Merchant of Record integration, even if the skill is not named.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- dodo-payments
- description
- Integrates Dodo Payments with the dodopayments SDK and the Dodo Payments MCP server. Covers checkout sessions, subscriptions and plan changes, webhook signature verification, usage-based (metered) billing, credits, license keys, products, discounts, localized pricing, customers and the customer portal, refunds and disputes, framework adapters, Better Auth, BillingSDK, mobile checkout, and test mode through go-live. Use whenever a task mentions Dodo Payments, dodopayments, a checkout or pay button, a subscription, a webhook from Dodo, metered or usage billing, credits, license keys, refunds, or a Merchant of Record integration, even if the skill is not named.
02 资源文件 17
- 参考文档references/better-auth.md4.7 KB
- 参考文档references/billing-sdk.md6.0 KB
- 参考文档references/checkout.md8.3 KB
- 参考文档references/credits.md7.5 KB
- 参考文档references/customers.md4.2 KB
- 参考文档references/discounts.md4.5 KB
- 参考文档references/framework-adapters.md13.2 KB
- 许可证references/license-keys.md7.7 KB
- 参考文档references/localized-pricing.md3.8 KB
- 参考文档references/mcp.md5.6 KB
- 参考文档references/mobile-checkout.md8.2 KB
- 参考文档references/products.md5.7 KB
- 参考文档references/refunds-disputes.md4.0 KB
- 参考文档references/subscriptions.md8.7 KB
- 参考文档references/testing-go-live.md5.0 KB
- 参考文档references/usage-billing.md5.1 KB
- 参考文档references/webhooks.md10.6 KB
03 SKILL.md 正文
Dodo Payments
Dodo Payments is a Merchant of Record: it is the legal seller, collects and remits sales tax, and handles chargebacks. Your code creates checkout sessions, verifies webhooks, and grants access.
When to use this skill and the standard path
Use it for any Dodo Payments integration or account task. Almost every integration follows the same three steps:
- Create a checkout session on the server with
client.checkoutSessions.create(...)and redirect the customer tocheckout_url. - Handle the webhook. Dodo POSTs a signed webhook to your endpoint. Verify it on the raw body with
client.webhooks.unwrap(...). - Grant access from the verified webhook:
payment.succeededfor one-time purchases,subscription.activefor subscriptions. Thereturn_urlredirect is a UI hint, never proof of payment.
import DodoPayments from 'dodopayments';
import express from 'express';
const client = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT === 'live_mode' ? 'live_mode' : 'test_mode',
});
const app = express();
// The webhook route takes the raw bytes, so mount it before express.json().
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
let event: DodoPayments.UnwrapWebhookEvent;
try {
event = client.webhooks.unwrap(req.body.toString('utf8'), {
headers: {
'webhook-id': req.headers['webhook-id'] as string,
'webhook-signature': req.headers['webhook-signature'] as string,
'webhook-timestamp': req.headers['webhook-timestamp'] as string,
},
});
} catch {
return res.status(401).json({ error: 'Invalid signature' });
}
if (event.type === 'payment.succeeded') await grantAccess(event.data.customer.customer_id);
if (event.type === 'subscription.active') await grantAccess(event.data.customer.customer_id);
res.json({ received: true });
});
app.use(express.json());
app.post('/api/checkout', async (req, res) => {
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'pdt_pro_monthly', quantity: 1 }], // map a plan slug server-side
customer: { email: 'customer@example.com' },
return_url: 'https://example.com/checkout/success',
});
res.json({ checkout_url: session.checkout_url });
});
Production handlers also deduplicate on webhook-id and process durably: see references/webhooks.md.
Client setup, test mode and live mode
| Test mode | Live mode | |
|---|---|---|
environment option |
'test_mode' |
'live_mode' (the SDK default) |
| Base URL | https://test.dodopayments.com |
https://live.dodopayments.com |
| API key prefix | dodo_test_ |
dodo_live_ |
- Install
dodopayments(npm, pip) orgithub.com/dodopayments/dodopayments-go. PHP, Ruby, Java and Kotlin SDKs exist too; use the MCPsearchtool for their setup. - Read the key from
DODO_PAYMENTS_API_KEYand the webhook secret fromDODO_PAYMENTS_WEBHOOK_KEY. - Narrow
environmentfrom an env var and default totest_mode, as above, so a missing variable never selects live mode. Keys, products, customers and webhooks never cross between modes. - Amounts are integers in the smallest currency unit: USD 10.00 is
1000. - The SDK retries connection errors, 408, 409, 429 and 5xx twice.
for awaitover a list method walks every page.
Safety rules that must never be broken
- Verify webhook signatures on the raw body. Use
client.webhooks.unwrap()or thestandardwebhookspackage. Never hand-roll HMAC and never verify re-serialized JSON.unsafeUnwrap()is only for the unsigned payloads thatdodo wh triggersends. - Use test mode until go-live. Pass
environment: 'test_mode'with adodo_test_key. Switch to live only through references/testing-go-live.md. - Never put API keys in client code. Browser bundles, mobile apps, desktop apps and CLIs never hold a Dodo API key, and Dodo has no publishable key. Call Dodo from your server; the client receives only a URL.
- Confirm before any write in live mode. Before a live refund, cancellation, plan change, charge, delete, or webhook endpoint change, name the resource ID and the effect and wait for the user's yes.
- Grant access only from a verified webhook or a server-side API read, never from
return_urlquery parameters, browser state, or a mobile SDK result.
Routing table
Read only the file the task needs.
| Task | Read |
|---|---|
| Pay button, checkout session options, overlay or inline checkout, static payment links, return URL | references/checkout.md |
| Checkout inside a React Native, Flutter, iOS or Android app | references/mobile-checkout.md |
| Trials, plan upgrades and downgrades, proration, pause, cancel, on-demand charges, dunning | references/subscriptions.md |
| Webhook endpoint, verification, idempotency, retries, the full list of webhook types | references/webhooks.md |
| Meters, usage events, per-unit pricing | references/usage-billing.md |
| Prepaid or included credits, balances, ledger, rollover, overage | references/credits.md |
| License key activation and validation in an app, CLI or desktop app | references/license-keys.md |
| Products, prices, add-ons, collections, images, digital files | references/products.md |
| Discount codes, eligibility, stacking, discounts on plan changes | references/discounts.md |
| Prices per country or currency, Adaptive Currency, purchasing power parity | references/localized-pricing.md |
| Customers, customer portal, saved payment methods, wallets | references/customers.md |
| Refunds, disputes, revoking and restoring access | references/refunds-disputes.md |
@dodopayments/* adapters for Next.js, Express, Hono, Fastify, Astro, Remix, SvelteKit, Nuxt, TanStack, Bun, Convex |
references/framework-adapters.md |
| Apps that use Better Auth | references/better-auth.md |
| Pricing tables and billing UI in React (BillingSDK) | references/billing-sdk.md |
| Test cards, the Dodo CLI, local webhooks, go-live checklist | references/testing-go-live.md |
The dodopayments MCP server: tools, sign-in, troubleshooting |
references/mcp.md |
Using the dodopayments MCP server
When the dodopayments MCP server is connected (https://mcp.dodopayments.com/mcp), it has five tools. The client signs in to Dodo Payments through OAuth when the server is added; no API key is needed.
| Tool | Use it to |
|---|---|
search_docs |
Find guides and docs pages |
read_docs_page |
Read a full docs page as Markdown |
search |
Find SDK and API methods, parameters and response fields |
execute |
Run TypeScript against the dodopayments SDK on the user's account |
feedback |
Report docs that were wrong, missing or confusing |
- Call
search_docsbefore writing integration code. The docs win over memory. - Call
searchbeforeexecute, so the script uses real method names and fields. - Use
executefor account actions (list products, look up a payment, create a test checkout session). Follow safety rule 4 for every live-mode write.
Details: references/mcp.md.
Old patterns
Recognise these in existing code and replace them in new code:
client.payments.create()andclient.subscriptions.create()are deprecated. Useclient.checkoutSessions.create().- The
discount_codestring is deprecated. Use thediscount_codesarray. - The
license_key.createdwebhook is legacy. Useentitlement_grant.created. client.licenseKeys.list(),retrieve()andupdate()are deprecated. Read keys through entitlement grants.type: "dynamic"checkout in the framework adapters calls the deprecated endpoints. Usetype: "session".
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.