.env file:
```env expandable theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
BETTER_AUTH_URL=http://localhost:3000
BETTER_AUTH_SECRET=your_better_auth_secret_here
```
src/lib/auth.ts:
```typescript expandable theme={null}
import { betterAuth } from "better-auth";
import {
dodopayments,
checkout,
portal,
webhooks,
usage,
} from "@dodopayments/better-auth";
import DodoPayments from "dodopayments";
export const dodoPayments = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
environment: "test_mode", // or "live_mode" for production
});
export const { auth, endpoints, client } = 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);
},
}),
usage(),
],
}),
],
});
```
environment to live\_mode for production.
src/lib/auth-client.ts:
```typescript expandable theme={null}
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()],
});
```
authClient.dodopayments.checkoutSession for new
integrations. The legacy checkout method is deprecated and kept
only for backward compatibility.
checkout method, checkoutSession
does not require billing information upfront as it will be taken from the user
at the checkout page. You can still override it by passing the
billing key in the argument.
checkout method,
checkoutSession takes customer's email and name from their
better-auth session, however, you can override it by passing the
customer object with email and name.
successUrl configured in the
server plugin. You do not need to include return\_url in the
client payload.
authClient.dodopayments.checkout method is deprecated. Use
checkoutSession instead for new implementations.
usage() plugin on the server to capture metered events and let customers inspect their usage-based billing.
* authClient.dodopayments.usage.ingest ingests events for the signed-in, email-verified user.
* authClient.dodopayments.usage.meters.list lists recent usage for the meters tied to that customer’s subscriptions.
```typescript expandable theme={null}
// Record a metered event (e.g., an API request)
const { error: ingestError } = await authClient.dodopayments.usage.ingest({
event_id: crypto.randomUUID(),
event_name: "api_request",
metadata: {
route: "/reports",
method: "GET",
},
// Optional Date; defaults to now if omitted
timestamp: new Date(),
});
if (ingestError) {
console.error("Failed to record usage", ingestError);
}
// List recent usage for the current customer
const { data: usage, error: usageError } =
await authClient.dodopayments.usage.meters.list({
query: {
page_size: 20,
meter_id: "mtr_yourMeterId", // optional
},
});
if (usage?.items) {
usage.items.forEach((event) => {
console.log(event.event_name, event.timestamp, event.metadata);
});
}
```
meter\_id when listing usage meters, all meters
tied to the customer’s subscriptions are returned.
/api/auth/dodopayments/webhooks.
https\://\/api/auth/dodopayments/webhooks ) in the Dodo Payments Dashboard and set it in your .env file:
```env theme={null}
DODO_PAYMENTS_WEBHOOK_SECRET=your_webhook_secret_here
```
DODO\_PAYMENTS\_API\_KEY in .env. -
Webhook signature mismatch: Ensure the webhook secret matches the one
set in the Dodo Payments Dashboard. - Customer not created: Confirm
createCustomerOnSignUp is set to true.
test\_mode before switching to live\_mode. - Log
webhook events for debugging and auditing.
mtr_) used by your usage-based plans
2. Decide which event names and metadata you will capture (e.g., api_request, route, method)
3. Ensure BetterAuth users verify their email addresses (the plugin enforces this before ingesting usage)
Configuration:
Add usage to your imports in src/lib/auth.ts:
import { dodopayments, usage } from "@dodopayments/better-auth";
Add the plugin to the use array:
use: [
usage(),
],
Usage Examples:
// Record a metered event for the signed-in customer
const { error: ingestError } = await authClient.dodopayments.usage.ingest({
event_id: crypto.randomUUID(),
event_name: "api_request",
metadata: {
route: "/reports",
method: "GET",
},
// Optional Date or ISO string; defaults to now
timestamp: new Date(),
});
if (ingestError) {
console.error("Failed to record usage", ingestError);
}
// List recent usage for the current customer
const { data: usage, error: usageError } =
await authClient.dodopayments.usage.meters.list({
query: {
page_size: 20,
meter_id: "mtr_yourMeterId", // optional filter
},
});
if (usage?.items) {
usage.items.forEach((event) => {
console.log(event.event_name, event.timestamp, event.metadata);
});
}
authClient.dodopayments.usage.ingest and
authClient.dodopayments.usage.meters.list. Timestamps older
than one hour or more than five minutes in the future are rejected.
meter_id when listing usage meters, all meters tied to
the customer’s active subscriptions are returned.
src/lib/auth.ts file to include all chosen plugins in the imports and use array:
Example for all four plugins:
import {
dodopayments,
checkout,
portal,
usage,
webhooks,
} from "@dodopayments/better-auth";
use: [
checkout({
// checkout configuration
}),
portal(),
usage(),
webhooks({
// webhook configuration
}),
];
Example for checkout + portal + usage:
import { dodopayments, checkout, portal, usage } from "@dodopayments/better-auth";
use: [
checkout({
// checkout configuration
}),
portal(),
usage(),
];
Example for just webhooks:
import { dodopayments, webhooks } from "@dodopayments/better-auth";
use: [
webhooks({
// webhook configuration
}),
];
IMPORTANT NOTES:
1. Complete Stage 1 before implementing any plugins
2. Ask the user which plugins they want to implement, or implement all four if no response
3. Only implement the plugins the user specifically requested
4. ALWAYS provide TODO lists for external actions the user needs to complete:
- API key generation and environment variable setup
- Product creation in Dodo Payments dashboard (for checkout plugin)
- Usage meter configuration and API event definition (for usage plugin)
- Webhook setup in Dodo Payments dashboard (for webhooks plugin)
- Domain name collection for webhook URL generation
5. For webhook plugin: Ask for the user's domain name and generate the exact webhook URL: https://[domain]/api/auth/dodopayments/webhooks
6. The usage plugin requires the BetterAuth session user to exist and have a verified email before ingesting or listing usage
7. All client methods return { data, error } objects for proper error handling
8. Use test_mode for development and live_mode for production
9. The webhook endpoint is automatically created and secured with signature verification (if webhooks plugin is selected)
10. Customer portal and subscription listing require user authentication (if portal plugin is selected)
11. Handle errors appropriately and test webhook functionality in development before going live
12. Present all external setup tasks as clear TODO lists with specific environment variable names
13. Use getCustomerParams to attach metadata or phone_number to DodoPayments customer records — the function receives the BetterAuth User object and runs on every customer creation and update
```
# Build with AI Coding Agents
Source: https://docs.dodopayments.com/developer-resources/build-with-ai-coding-agents
Use the Dodo Agent Plugin to build integrations with Claude Code, Codex CLI, Cursor, and OpenCode — MCP servers and skills in one install.
The Dodo Agent Plugin wires two MCP servers and eight integration skills into your AI coding agent in a single install. It works with **Claude Code**, **Codex CLI**, **Cursor**, and **OpenCode** — and the MCP servers and skills CLI work with any MCP-compatible client.
.env file in your project root:
```env expandable theme={null}
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url
```
.env file or secrets to version control.
Bun.serve().
?productId=pdt\_xxx).
USD).
1000 for \$10.00).
metadata\_ will be passed as metadata.
productId is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
?customer\_id=cus\_123).
true, sends an email to the customer with the portal link.
customer\_id is missing.
webhookKey. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
createPayment mutation to record successful payments or a createSubscription mutation to manage subscription state.
true, sends an email to the customer with the portal link.
DODO\_PAYMENTS\_WEBHOOK\_SECRET. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
.env file in your project root:
```env expandable theme={null}
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=your-return-url
```
.env file or secrets to version control.
?productId=pdt\_nZuwz45WAs64n3l07zpQR).
USD).
1000 for \$10.00).
metadata\_ will be passed as metadata.
productId is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
?customer\_id=cus\_123).
true, sends an email to the customer with the portal link.
customer\_id is missing.
webhookKey. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
.env file in your project root:
```env expandable theme={null}
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""
```
.env file or secrets to version control.
?productId=pdt\_nZuwz45WAs64n3l07zpQR).
USD).
1000 for \$10.00).
metadata\_ will be passed as metadata.
productId is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
?customer\_id=cus\_123).
true, sends an email to the customer with the portal link.
customer\_id is missing.
webhookKey. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
.env file in your project root:
```env expandable theme={null}
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode""
```
.env file or secrets to version control.
?productId=pdt\_nZuwz45WAs64n3l07zpQR).
USD).
1000 for \$10.00).
metadata\_ will be passed as metadata.
productId is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
?customer\_id=cus\_123).
true, sends an email to the customer with the portal link.
customer\_id is missing.
webhookKey. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
.env file in your project root:
```env theme={null}
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"
```
.env file or secrets to version control.
?productId=pdt\_nZuwz45WAs64n3l07zpQR).
USD).
1000 for \$10.00).
metadata\_ will be passed as metadata.
productId is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
?customer\_id=cus\_123).
true, sends an email to the customer with the portal link.
customer\_id is missing.
webhookKey. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
@dodopayments/nuxt to your modules array and configure it:
```typescript nuxt.config.ts expandable theme={null}
export default defineNuxtConfig({
modules: ["@dodopayments/nuxt"],
devtools: { enabled: true },
compatibilityDate: "2025-02-25",
runtimeConfig: {
private: {
bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
webhookKey: process.env.NUXT_PRIVATE_WEBHOOK_KEY,
environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
returnUrl: process.env.NUXT_PRIVATE_RETURNURL
},
}
});
```
.env file or secrets to version control.
server/routes/api/ directory.
productId is missing or invalid, the handler returns a 400 response.
customer\_id as a query parameter.
customer\_id (required): The customer ID for the portal session (e.g., ?customer\_id=cus\_123)
* send\_email (optional, boolean): If true, sends an email to the customer with the portal link.
customer\_id is missing.
?productId=pdt\_nZuwz45WAs64n3l07zpQR).
USD).
1000 for \$10.00).
metadata\_ will be passed as metadata.
productId is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
?customer\_id=cus\_123).
true, sends an email to the customer with the portal link.
customer\_id is missing.
webhookKey. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
2500.
product\_price. If false, fees are added on top.
.env file in your project root:
```env expandable theme={null}
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secret
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
```
.env file or secrets to version control.
?productId=pdt\_nZuwz45WAs64n3l07zpQR).
USD).
1000 for \$10.00).
metadata\_ will be passed as metadata.
productId is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
?customer\_id=cus\_123).
true, sends an email to the customer with the portal link.
customer\_id is missing.
webhookKey. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
.env file in your project root:
```env expandable theme={null}
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
```
.env file or secrets to version control.
?productId=pdt\_nZuwz45WAs64n3l07zpQR).
USD).
1000 for \$10.00).
metadata\_ will be passed as metadata.
productId is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
?customer\_id=cus\_123).
true, sends an email to the customer with the portal link.
customer\_id is missing.
webhookKey. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
.env file in your project root:
```env expandable theme={null}
DODO_PAYMENTS_API_KEY=your-api-key
DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
DODO_PAYMENTS_RETURN_URL=your-return-url
DODO_PAYMENTS_ENVIRONMENT="test_mode" or "live_mode"
```
.env file or secrets to version control.
?productId=pdt\_nZuwz45WAs64n3l07zpQR).
USD).
1000 for \$10.00).
metadata\_ will be passed as metadata.
productId is missing, the handler returns a 400 response. Invalid query parameters also result in a 400 response.
?customer\_id=cus\_123).
true, sends an email to the customer with the portal link.
customer\_id is missing.
webhookKey. Returns 401 if verification fails.
* **Payload Validation:** Validated with Zod. Returns 400 for invalid payloads.
* **Error Handling:**
* 401: Invalid signature
* 400: Invalid payload
* 500: Internal error during verification
* **Event Routing:** Calls the appropriate event handler based on the payload type.
### Supported Webhook Event Handlers
- Payment was disputed
- Insufficient balance in wallet
- Bank issue
Sentra is an AI agent that integrates, analyzes, and acts on billing and payments directly in your IDE. Ask questions, build integrations, or plan billing architectures - all by describing what you want. Get started with Sentra →
Install our AI agent in VS Code, Cursor, or Windsurf. Describe what you want - SDK integration, webhook handlers, subscription flows - and Sentra generates the code for you. Install Sentra →
Tip: Complete the form digitally before printing and signing for best results.
Note: This will use the existing payment information of the customer to upgrade/downgrade the plan. ## Scheduled Plan Changes Use the `effective_at` parameter to control when the plan change takes effect: | Value | Behavior | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `immediately` | Apply the plan change right away. This is the default. | | `next_billing_date` | Schedule the change for the next billing date. The customer retains access to their current plan until the billing period ends. |
Use our AI assistant in VS Code, Cursor, or Windsurf to generate SDK/API code, webhook handlers, and more, just by describing what you want. Try Sentra: AI-Powered Integration →
MailKit
Prepaid transactional email, billed per send.
1. Subscribe to MailKit ($19/mo, 5,000 emails)
2. Check your balance
3. Send a transactional email
4. Run low? Buy a top-up pack
```Use our AI assistant in VS Code, Cursor, or Windsurf to generate SDK/API code, webhook handlers, credit grants, and more — just by describing what you want. Try Sentra: AI-Powered Integration →
NeuralAPI Demo
After completing checkout, copy the customer ID from your Dodo Payments dashboard (Customers → most recent) and paste here.
1. Subscribe to a Plan
2. Generate AI Response (deducts tokens)
3. Live Token Balance
4. Buy a Top-Up Pack
```Use our AI assistant in VS Code, Cursor, or Windsurf to generate SDK/API code, LLM Blueprint integration code, webhooks, and more - just by describing what you want. Try Sentra: AI-Powered Integration →
🤖 AI Chat Assistant
Powered by AI-SDK & Dodo Payments
{/* Left Side - Checkout Form */}
{/* Right Side - Custom Order Summary */}
);
}
```
## API Reference
### Configuration
#### Initialize Options
```typescript theme={null}
interface InitializeOptions {
mode: "test" | "live";
displayType: "inline"; // Required for inline checkout
onEvent: (event: CheckoutEvent) => void;
}
```
| Option | Type | Required | Description |
| ------------- | ----------------------- | -------- | ------------------------------------------------ |
| `mode` | `"test" \| "live"` | Yes | Environment mode. |
| `displayType` | `"inline" \| "overlay"` | Yes | Must be set to `"inline"` to embed the checkout. |
| `onEvent` | `function` | Yes | Callback function for handling checkout events. |
#### Checkout Options
```typescript theme={null}
export type FontSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
export type FontWeight = "normal" | "medium" | "bold" | "extraBold";
interface CheckoutOptions {
checkoutUrl: string;
elementId: string; // Required for inline checkout
options?: {
showTimer?: boolean;
showSecurityBadge?: boolean;
payButtonText?: string;
fontSize?: FontSize;
fontWeight?: FontWeight;
};
}
```
| Option | Type | Required | Description |
| --------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `checkoutUrl` | `string` | Yes | Checkout session URL. |
| `elementId` | `string` | Yes | The `id` of the DOM element where the checkout should be rendered. |
| `options.showTimer` | `boolean` | No | Show or hide the checkout timer. Defaults to `true`. When disabled, you will receive the `checkout.link_expired` event when the session expires. |
| `options.showSecurityBadge` | `boolean` | No | Show or hide the security badge. Defaults to `true`. |
| `options.payButtonText` | `string` | No | Custom text to display on the pay button. |
| `options.fontSize` | `FontSize` | No | Global font size for the checkout. |
| `options.fontWeight` | `FontWeight` | No | Global font weight for the checkout. |
### Methods
#### Open Checkout
Opens the checkout frame in the specified container.
```typescript theme={null}
DodoPayments.Checkout.open({
checkoutUrl: "https://test.dodopayments.com/session/cks_123",
elementId: "dodo-inline-checkout"
});
```
You can also pass additional options to customize the checkout behavior:
```typescript theme={null}
DodoPayments.Checkout.open({
checkoutUrl: "https://test.dodopayments.com/session/cks_123",
elementId: "dodo-inline-checkout",
options: {
showTimer: false,
showSecurityBadge: false,
payButtonText: "Pay Now",
},
});
```
#### Close Checkout
Programmatically removes the checkout frame and cleans up event listeners.
```typescript theme={null}
DodoPayments.Checkout.close();
```
#### Check Status
Returns whether the checkout frame is currently injected.
```typescript theme={null}
const isOpen = DodoPayments.Checkout.isOpen();
// Returns: boolean
```
### Events
The SDK provides real-time events through the `onEvent` callback. For inline checkout, `checkout.breakdown` is particularly useful for syncing your UI.
| Event Type | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `checkout.opened` | Checkout frame has been loaded. |
| `checkout.form_ready` | Checkout form is ready to receive user input. Useful for hiding loading states and showing the checkout UI. |
| `checkout.breakdown` | Fired when prices, taxes, or discounts are updated. |
| `checkout.customer_details_submitted` | Customer details have been submitted. |
| `checkout.pay_button_clicked` | Fired when the customer clicks the pay button. Useful for analytics and tracking conversion funnels. |
| `checkout.redirect` | Checkout will perform a redirect (e.g., to a bank page). |
| `checkout.error` | An error occurred during checkout. |
| `checkout.link_expired` | Fired when the checkout session expires. Only received when `showTimer` is set to `false`. |
#### Checkout Breakdown Data
The `checkout.breakdown` event provides the following data:
```typescript theme={null}
interface CheckoutBreakdownData {
subTotal?: number; // Amount in cents
discount?: number; // Amount in cents
tax?: number; // Amount in cents
total?: number; // Amount in cents
currency?: string; // e.g., "USD"
finalTotal?: number; // Final amount including adjustments
finalTotalCurrency?: string; // Currency for the final total
}
```
#### Understanding the Breakdown Event
The `checkout.breakdown` event is the primary way to keep your application's UI in sync with the Dodo Payments checkout state.
**When it fires:**
* **On initialization**: Immediately after the checkout frame is loaded and ready.
* **On address change**: Whenever the customer selects a country or enters a postal code that results in a tax recalculation.
**Field Details:**
| Field | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subTotal` | The sum of all line items in the session before any discounts or taxes are applied. |
| `discount` | The total value of all applied discounts. |
| `tax` | The calculated tax amount. In `inline` mode, this updates dynamically as the user interacts with the address fields. |
| `total` | The mathematical result of `subTotal - discount + tax` in the session's base currency. |
| `currency` | The ISO currency code (e.g., `"USD"`) for the standard subtotal, discount, and tax values. |
| `finalTotal` | The actual amount the customer is charged. This may include additional foreign exchange adjustments or local payment method fees that aren't part of the basic price breakdown. |
| `finalTotalCurrency` | The currency in which the customer is actually paying. This can differ from `currency` if purchasing power parity or local currency conversion is active. |
**Key Integration Tips:**
1. **Currency Formatting**: Prices are always returned as integers in the smallest currency unit (e.g., cents for USD, yen for JPY). To display them, divide by 100 (or the appropriate power of 10) or use a formatting library like `Intl.NumberFormat`.
2. **Handling Initial States**: When the checkout first loads, `tax` and `discount` may be `0` or `null` until the user provides their billing information or applies a code. Your UI should handle these states gracefully (e.g., showing a dash `—` or hiding the row).
3. **The "Final Total" vs "Total"**: While `total` gives you the standard price calculation, `finalTotal` is the source of truth for the transaction. If `finalTotal` is present, it reflects exactly what will be charged to the customer's card, including any dynamic adjustments.
4. **Real-time Feedback**: Use the `tax` field to show users that taxes are being calculated in real-time. This provides a "live" feel to your checkout page and reduces friction during the address entry step.
## Implementation Options
### Package Manager Installation
Install via npm, yarn, or pnpm as shown in the [Step-by-Step Integration Guide](#step-by-step-integration-guide).
### CDN Implementation
For quick integration without a build step, you can use our CDN:
```html theme={null}
Order Summary
{breakdown.subTotal && (
{(breakdown.finalTotal ?? breakdown.total) && (
Subtotal
{format(breakdown.subTotal, currency)}
)}
{breakdown.discount && (
Discount
{format(breakdown.discount, currency)}
)}
{breakdown.tax != null && (
Tax
{format(breakdown.tax, currency)}
)}
{(breakdown.finalTotal ?? breakdown.total) && (
Total
{format(breakdown.finalTotal ?? breakdown.total, breakdown.finalTotalCurrency ?? currency)}
)}
Dodo iframe] CP[Your Checkout Page] IC -->|events| CP end subgraph Server["Your Server"] WH[Webhook Handler] DB[(Database)] API[Status API] WH --> DB API --> DB end subgraph Dodo["Dodo Payments"] PP[Payment Processor] end CP -->|Poll for status| API PP -->|Webhooks| WH IC -.->|Payment request| PP ``` ### Implementation Steps **1. Listen for checkout events** - When the user clicks pay, start preparing to verify the status: ```typescript theme={null} onEvent: (event) => { if (event.event_type === 'checkout.pay_button_clicked') { // Start polling your server for confirmed status startPolling(); } } ``` **2. Poll your server** - Create an endpoint that checks your database for the payment status (updated by webhooks): ```typescript theme={null} // Poll every 2 seconds until status is confirmed const interval = setInterval(async () => { const { status } = await fetch(`/api/payments/${paymentId}/status`).then(r => r.json()); if (status === 'succeeded' || status === 'failed') { clearInterval(interval); handlePaymentResult(status); } }, 2000); ``` **3. Handle webhooks server-side** - Update your database when Dodo sends `payment.succeeded` or `payment.failed` webhooks. See our [Webhooks documentation](/developer-resources/webhooks) for details. ## Troubleshooting
confirm=true, sessions are valid for 15 minutes and all required fields must be provided.
[https://example.com/?payment\_id=pay\_ts2ySpzg07phGeBZqePbH\&status=succeeded\&email=customer%40example.com](https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH\&status=succeeded\&email=customer%40example.com)If the product has license keys enabled, a `license_key` parameter is also appended (comma-separated for multiple keys):
[https://example.com/?payment\_id=pay\_xxx\&status=succeeded\&license\_key=LK-001\&email=customer%40example.com](https://example.com/?payment_id=pay_xxx\&status=succeeded\&license_key=LK-001\&email=customer%40example.com)
disable... flag to true:
showDiscounts=false will disable and hide the discounts section in the checkout form. Use this if you want to prevent customers from entering coupon or promo codes during checkout.
metadata\_orderId=123).?session=sess\_1a2b3c4d). The stored information persists through page refreshes and is accessible throughout the checkout process.
Payment Successful!
Thank you for your purchase.
Payment Failed
Please try again or contact support.
Seat-Based Pricing Demo
Generate checkout links with custom seat quantities:
invoice\_id and payment\_id are returned only when an immediate charge and/or invoice is created during the plan change. Always rely on webhook events (e.g., payment.succeeded, subscription.plan\_changed) to confirm outcomes.
difference\_immediately are subscription-scoped and distinct from Credit-Based Billing entitlements. They automatically apply to future renewals of the same subscription and are not transferable between subscriptions.
A minimal subscription starter kit built with Next.js, Supabase, and Dodo Payments. This boilerplate helps you quickly set up a subscription-based SaaS with authentication, payments, and webhooks. Dodo Payments Supabase Subscription Starter
Pays $200] -->|incl. $30 tax| B[🏦 Dodo Payments] B -->|$30| C[🏛️ Tax Authority] B -->|$162.40| D[💼 You] ``` ### Example Payout Breakdown | Line Item | Amount | | ---------------------- | -----------: | | Customer Payment | \$200.00 | | Sales Tax (15% VAT) | −\$30.00 | | Dodo Platform Fee (4%) | −\$8.00 | | Payment Processing | −\$0.60 | | **Your Payout** | **\$162.40** | ## When to Choose MoR vs. PSP
Payment Successful!
Hi ${p.customer.name},
Your payment of $${(p.total_amount / 100).toFixed(2)} has been processed successfully.
- Payment ID: ${p.payment_id}
- Amount: $${(p.total_amount / 100).toFixed(2)}
- Date: ${new Date(webhook.payload.timestamp).toLocaleDateString()}
- Method: ${p.payment_method || "Unknown"}
Thank you for your business!
`, text: `Payment Successful! Your payment of $${(p.total_amount / 100).toFixed(2)} has been processed. Payment ID: ${p.payment_id}` }; } return webhook; } ``` ### Subscription Welcome Email ```javascript subscription_welcome.js icon="js" expandable theme={null} function handler(webhook) { if (webhook.eventType === "subscription.active") { const s = webhook.payload.data; webhook.url = "https://api.resend.com/emails"; webhook.payload = { from: "welcome@yourdomain.com", to: [s.customer.email], subject: "Welcome to Your Subscription!", html: `Welcome to Your Subscription!
Hi ${s.customer.name},
Your subscription has been activated successfully.
- Subscription ID: ${s.subscription_id}
- Product: ${s.product_id}
- Amount: $${(s.recurring_pre_tax_amount / 100).toFixed(2)}/${s.payment_frequency_interval}
- Next Billing: ${new Date(s.next_billing_date).toLocaleDateString()}
You can manage your subscription anytime from your account dashboard.
`, text: `Welcome! Your subscription is now active. Amount: $${(s.recurring_pre_tax_amount / 100).toFixed(2)}/${s.payment_frequency_interval}` }; } return webhook; } ``` ### Payment Failure Notification ```javascript payment_failure.js icon="js" expandable theme={null} function handler(webhook) { if (webhook.eventType === "payment.failed") { const p = webhook.payload.data; webhook.url = "https://api.resend.com/emails"; webhook.payload = { from: "support@yourdomain.com", to: [p.customer.email], subject: "Payment Failed - Action Required", html: `Payment Failed
Hi ${p.customer.name},
We were unable to process your payment of $${(p.total_amount / 100).toFixed(2)}.
- Payment ID: ${p.payment_id}
- Amount: $${(p.total_amount / 100).toFixed(2)}
- Error: ${p.error_message || "Payment processing failed"}
Please update your payment method or contact support for assistance.
Update Payment Method `, text: `Payment Failed: We couldn't process your $${(p.total_amount / 100).toFixed(2)} payment. Please update your payment method.` }; } return webhook; } ``` ## Tips * Use verified sender domains for better deliverability * Include both HTML and text versions of emails * Personalize content with customer data * Use clear, action-oriented subject lines * Include unsubscribe links for compliance * Test email templates before going live ## TroubleshootingIncludes signature verification and typed event handling for Express, Hono, Elysia, and more.
By @sancho1952007 (Sancho Godinho)
`TypeScript` `Webhooks` `Node`
Provides typed models and helpers to call core endpoints from Rust services.
By @Muhammad-Owais-Warsi
`Rust` `SDK`
Easily integrate Dodo Payments APIs into your Laravel applications with ready-made service classes and helpers.
By @codeplugtech
`PHP` `Laravel` `SDK`
It comes with predefined structures for requests and responses and uses a builder pattern to simplify constructing and sending payment-related API calls.
By @PiyushXCoder
`Rust` `SDK`
Production-ready payment microservice built with FastAPI that handles payments for multiple applications using Dodo Payments.
Features include
`credit management`, `subscription support`, `webhook processing with idempotency`, `complete audit trails`, `MixPanel Analytics`, `Backend-to-backend architecture with API key authentication`.
By @aniketkarne (Aniket Karne)
`Python` `Fast-API` `Library`
20 resources, 60+ methods, typed models, and a drop-in DodoCheckoutButton widget with WebView.
By @MrPrinceRawat
`Dart` `Flutter` `SDK`
Drop-in provider to accept payments in WHMCS using Dodo Payments.
By @Akash123a5
`PHP` `WHMCS` `Plugin`
Includes example checkout flow, API wiring, and environment configuration.
By @snehalsaurabh
`Boilerplate`
Minimal setup to create and confirm payments with example pages.
By @vanshcodeworks
`Boilerplate`
Demonstrates clean architecture around payment intents and webhooks.
By @rasadov
`Template`
You can go from an empty folder to a working app in an afternoon.
By @KissuChaudhary
`TypeScript` `Next.js` `Boilerplate`
By @github_username
`LANGUAGE` `FRAMEWORK` `CATEGORY`