.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
```
# Bun Adaptor
Source: https://docs.dodopayments.com/developer-resources/bun-adaptor
Learn how to integrate Dodo Payments with your Bun server project using our Bun Adaptor. Covers checkout, customer portal, webhooks, and secure environment setup.
.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
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
- 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. ## Payment Failure Handling Use the `on_payment_failure` parameter to control what happens when the plan change payment fails: | Value | Behavior | | ---------------- | -------------------------------------------------------------------------------------- | | `prevent_change` | Keep subscription on current plan until payment succeeds. Plan change remains pending. | | `apply_change` | Apply plan change immediately regardless of payment outcome. This is the default. |
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;
manualRedirect?: boolean;
themeConfig?: ThemeConfig;
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.manualRedirect` | `boolean` | No | When enabled, the checkout will not automatically redirect after completion. Instead, you will receive `checkout.status` and `checkout.redirect_requested` events to handle the redirect yourself. |
| `options.themeConfig` | `ThemeConfig` | No | Custom theme configuration. |
| `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,
manualRedirect: true,
payButtonText: "Pay Now",
},
});
```
When using `manualRedirect`, handle the checkout completion in your `onEvent` callback:
```typescript theme={null}
DodoPayments.Initialize({
mode: "test",
displayType: "inline",
onEvent: (event) => {
if (event.event_type === "checkout.status") {
const status = event.data?.message?.status;
// Handle status: "succeeded", "failed", or "processing"
}
if (event.event_type === "checkout.redirect_requested") {
const redirectUrl = event.data?.message?.redirect_to;
// Redirect the customer manually
window.location.href = redirectUrl;
}
if (event.event_type === "checkout.link_expired") {
// Handle expired checkout session
}
},
});
```
#### 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.status` | Fired when `manualRedirect` is enabled. Contains the checkout status (`succeeded`, `failed`, or `processing`). |
| `checkout.redirect_requested` | Fired when `manualRedirect` is enabled. Contains the URL to redirect the customer to. |
#### 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
}
```
#### Checkout Status Event Data
When `manualRedirect` is enabled, you receive the `checkout.status` event with the following data:
```typescript theme={null}
interface CheckoutStatusEventData {
message: {
status?: "succeeded" | "failed" | "processing";
};
}
```
#### Checkout Redirect Requested Event Data
When `manualRedirect` is enabled, you receive the `checkout.redirect_requested` event with the following data:
```typescript theme={null}
interface CheckoutRedirectRequestedEventData {
message: {
redirect_to?: string;
};
}
```
#### 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.status') { // 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. ### Handling Redirects (3DS, Google Pay, UPI) When using `manualRedirect: true`, certain payment methods require redirecting the user away from your page for authentication: * **3D Secure (3DS)** - Card authentication * **Google Pay** - Wallet authentication on some flows * **UPI** - Indian payment method redirects When a redirect is required, you'll receive the `checkout.redirect_requested` event. Redirect the user to the provided URL: ```typescript theme={null} if (event.event_type === 'checkout.redirect_requested') { const redirectUrl = event.data?.message?.redirect_to; // Save payment ID before redirect, then redirect sessionStorage.setItem('pendingPaymentId', paymentId); window.location.href = redirectUrl; } ``` After authentication completes (success or failure), the user returns to your page. **Do not assume success just because the user returned.** Instead: 1. Check if the user is returning from a redirect (e.g., via `sessionStorage`) 2. Start polling your server for the confirmed payment status 3. Show a "Verifying payment..." state while polling 4. Display success/failure UI based on the server-confirmed status
confirm=true, sessions are valid for 15 minutes and all required fields must be provided.
[https://example.com/?payment\_id=pay\_ts2ySpzg07phGeBZqePbH\&status=succeeded](https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH\&status=succeeded)
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 Customer Credits. They automatically apply to future renewals of the same subscription and are not transferable between subscriptions.
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
Includes 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`
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`
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 ## Troubleshooting