> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Adaptador de TanStack
> Añade las rutas del servidor de checkout, Customer Portal y webhooks de Dodo Payments a un proyecto de TanStack Start con el paquete @dodopayments/tanstack.
El paquete `@dodopayments/tanstack` proporciona a tu proyecto de TanStack Start tres controladores de solicitudes. `Checkout` devuelve URL de checkout, `CustomerPortal` dirige al cliente a Customer Portal y `Webhooks` verifica los eventos de webhook y los envía a tu código. Cada controlador acepta un `Request` estándar y devuelve un `Response`, por lo que puedes llamarlo desde un controlador de rutas del servidor.
Crea URL de checkout con flujos estáticos, dinámicos y de sesiones de checkout.
Permite que los clientes gestionen sus suscripciones y datos.
Recibe y procesa eventos de webhook de Dodo Payments.
## Instalación
Ejecuta este comando en la raíz de tu proyecto:
```bash theme={null}
npm install @dodopayments/tanstack
```
El paquete también necesita `zod` 3.25 o posterior, que aparece como dependencia peer.
Crea un archivo `.env` en la raíz de tu proyecto. Crea la API key en **Developer → API Keys**. Añade el endpoint de webhook en **Developer → Webhooks** y copia su **Signing secret** en `DODO_PAYMENTS_WEBHOOK_KEY`:
```env expandable 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
# test_mode or live_mode
DODO_PAYMENTS_ENVIRONMENT=test_mode
```
TanStack Start carga archivos `.env`, y las rutas del servidor leen los valores desde `process.env`. `DODO_PAYMENTS_RETURN_URL` es la página a la que llegan los clientes después del checkout. Si no pasas un entorno, los controladores usan `live_mode`. Una API key del modo de prueba solo funciona con `test_mode`.
Nunca confirmes tu archivo `.env` ni tus secretos en el control de versiones.
## Ejemplos de controladores de rutas
Los ejemplos son rutas del servidor de TanStack Start en `src/routes/api/`. Cada una define sus controladores en `server.handlers` dentro de `createFileRoute`. Las versiones anteriores de TanStack Start, como la 1.129, definen las rutas del servidor con `createServerFileRoute` de `@tanstack/react-start/server` y una llamada a `.methods()`. Los controladores de Dodo Payments funcionan de la misma manera con ambas API: pásales el `request`.
Usa este controlador para añadir el checkout de Dodo Payments a tu aplicación. El controlador `GET` proporciona checkout estático. El controlador `POST` proporciona sesiones de checkout o checkout dinámico cuando estableces `type: "dynamic"`. El ejemplo de checkout dinámico presupone que estableces `type: "dynamic"`.
```typescript TanStack Route Handler expandable theme={null}
// src/routes/api/checkout.ts
import { Checkout } from "@dodopayments/tanstack";
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/api/checkout")({
server: {
handlers: {
GET: async ({ request }) => {
return Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
type: "static", // optional, defaults to 'static'
})(request);
},
POST: async ({ request }) => {
return Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
type: "session", // or "dynamic" for dynamic checkout
})(request);
},
},
},
});
```
```bash Static Checkout cURL Example theme={null}
curl --request GET \
--url 'https://example.com/api/checkout?productId=pdt_fqJhl7pxKWiLhwQR042rh'
```
```bash Dynamic Checkout cURL Example expandable theme={null}
curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--data '{
"billing": {
"city": "Austin",
"country": "US",
"state": "TX",
"street": "123 Main St",
"zipcode": "78701"
},
"customer": {
"email": "customer@example.com",
"name": "John Doe"
},
"metadata": {},
"payment_link": true,
"product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
"quantity": 1,
"billing_currency": "USD",
"discount_codes": ["IKHZ23M9GQ"],
"return_url": "https://example.com",
"trial_period_days": 10
}'
```
```bash Checkout Session cURL Example expandable theme={null}
curl --request POST \
--url https://example.com/api/checkout \
--header 'Content-Type: application/json' \
--data '{
"product_cart": [
{
"product_id": "pdt_QMDuvLkbVzCRWRQjLNcs",
"quantity": 1
}
],
"customer": {
"email": "customer@example.com",
"name": "John Doe"
},
"return_url": "https://example.com/success"
}'
```
Usa este controlador para enviar a los clientes a Dodo Payments Customer Portal, donde pueden gestionar sus suscripciones y datos.
```typescript TanStack Route Handler expandable theme={null}
// src/routes/api/customer-portal.ts
import { CustomerPortal } from "@dodopayments/tanstack";
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/api/customer-portal")({
server: {
handlers: {
GET: async ({ request }) => {
return CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
})(request);
},
},
},
});
```
```bash Customer Portal cURL Example theme={null}
curl --request GET \
--url 'https://example.com/api/customer-portal?customer_id=cus_9VuW4K7O3GHwasENg31m&send_email=true'
```
Usa este controlador para recibir eventos de webhook de Dodo Payments en tu aplicación de TanStack Start y verificar sus firmas.
```typescript TanStack Route Handler expandable theme={null}
// src/routes/api/webhook.ts
import { Webhooks } from "@dodopayments/tanstack";
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/api/webhook")({
server: {
handlers: {
POST: async ({ request }) => {
return Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY!,
onPayload: async (payload) => {
console.log(payload);
},
})(request);
},
},
},
});
```
## Controlador de rutas de checkout
El controlador de checkout admite las tres formas de aceptar pagos con Dodo Payments:
* **Enlaces de pago estáticos:** URL que se pueden compartir y que recaudan pagos sin código.
* **Enlaces de pago dinámicos:** Enlaces de pago que generas con datos personalizados. Usan endpoints obsoletos.
* **Sesiones de checkout:** Checkout alojado con un carrito de productos, datos del cliente y opciones de personalización. Este es el flujo recomendado.
`Checkout` acepta estas opciones:
| Opción | Tipo | Descripción |
| - | - | - |
| `bearerToken` | `string` | Tu API key de Dodo Payments. |
| `environment` | `string` | `test_mode` o `live_mode`. El valor predeterminado es `live_mode`. |
| `returnUrl` | `string` | Opcional. La URL a la que checkout redirige al cliente después del pago. Un `return_url` en el cuerpo de un POST tiene prioridad. |
| `type` | `string` | El flujo de checkout: `static`, `dynamic` o `session`. El valor predeterminado es `static`. |
El controlador proporciona checkout estático para solicitudes `GET`. Para solicitudes `POST`, crea un enlace de pago dinámico cuando `type` es `dynamic` y, en caso contrario, crea una sesión de checkout.
### Parámetros de consulta compatibles
Identificador del producto, por ejemplo `?productId=pdt_nZuwz45WAs64n3l07zpQR`.
Cantidad del producto.
Nombre completo del cliente. Se ignora si se proporciona `firstName` o `lastName`.
Nombre del cliente.
Apellidos del cliente.
Dirección de correo electrónico del cliente.
País del cliente, como código ISO 3166-1 alpha-2.
Dirección postal del cliente.
Ciudad del cliente.
Estado o provincia del cliente.
Código postal del cliente.
Establécelo en `true` para deshabilitar el campo de nombre completo.
Establécelo en `true` para deshabilitar el campo de nombre.
Establécelo en `true` para deshabilitar el campo de apellidos.
Establécelo en `true` para deshabilitar el campo de correo electrónico.
Establécelo en `true` para deshabilitar el campo de país.
Establécelo en `true` para deshabilitar el campo de dirección.
Establécelo en `true` para deshabilitar el campo de ciudad.
Establécelo en `true` para deshabilitar el campo de estado.
Establécelo en `true` para deshabilitar el campo de código postal.
Moneda del pago, por ejemplo `USD`.
Muestra u oculta el selector de moneda.
Fija el importe cobrado, en unidades principales de la moneda, por ejemplo `12.5` para \$12.50. Solo funciona con productos Pay What You Want y se ignora si está por debajo del precio mínimo del producto.
Muestra u oculta la sección de descuentos.
Cualquier parámetro de consulta que empiece por `metadata_` se pasa al checkout como metadata, por ejemplo `metadata_orderId=123`.
Una bandera de desactivación solo tiene efecto cuando el campo correspondiente tiene un valor, por ejemplo `email` con `disableEmail=true`. El controlador añade `returnUrl` de su configuración al enlace como `redirect_url`.
Si falta `productId`, el controlador devuelve una respuesta 400. Los parámetros de consulta no válidos o un producto que no existe en tu cuenta también devuelven 400.
### Formato de respuesta
El checkout estático devuelve una respuesta JSON con la URL de checkout. En el modo de prueba, la URL usa `test.checkout.dodopayments.com`:
```json theme={null}
{
"checkout_url": "https://test.checkout.dodopayments.com/buy/pdt_fqJhl7pxKWiLhwQR042rh?quantity=1&redirect_url=https%3A%2F%2Fyourdomain.com%2Fcheckout%2Fsuccess"
}
```
* Envía los parámetros como cuerpo JSON en una solicitud POST.
* Admite pagos únicos y recurrentes. El controlador recupera el producto y, después, crea una suscripción si el producto es recurrente o un pago único en caso contrario.
* El cuerpo necesita `billing` (con `street`, `city`, `state`, `country` y `zipcode`) y `customer`, además de `product_id` o `product_cart`. Las suscripciones necesitan `product_id`.
* Para consultar todos los campos compatibles del cuerpo, visita:
* [Cuerpo de solicitud para un producto de pago único](https://docs.dodopayments.com/api-reference/payments/post-payments)
* [Cuerpo de solicitud para un producto de suscripción](https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions)
El checkout dinámico actúa como proxy de los endpoints obsoletos `POST /payments` y `POST /subscriptions`. Sigue funcionando para las integraciones existentes, pero las integraciones nuevas deben usar sesiones de checkout.
### Formato de respuesta
El checkout dinámico devuelve una respuesta JSON con el enlace de pago como URL de checkout:
```json theme={null}
{
"checkout_url": "https://test.checkout.dodopayments.com/cbq"
}
```
Las sesiones de checkout crean un checkout alojado para compras únicas y suscripciones, con control total sobre la personalización. `product_cart` es el único campo obligatorio y necesita al menos un producto. Si el cuerpo no contiene `return_url`, el controlador usa `returnUrl` de su configuración.
Cada `checkout_url` funciona una vez y caduca después de 24 horas o después de 15 minutos cuando pasas `confirm: true`. Una sesión creada con `payment_method_id` no devuelve `checkout_url`, por lo que el controlador responde con 400.
Para obtener más información y consultar todos los campos compatibles, visita la [Guía de integración de Checkout Sessions](https://docs.dodopayments.com/developer-resources/checkout-session).
### Formato de respuesta
Las sesiones de checkout devuelven una respuesta JSON con la URL de checkout:
```json theme={null}
{
"checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}
```
## Controlador de rutas de Customer Portal
El controlador de rutas de Customer Portal crea una sesión de Customer Portal para el cliente que indiques y redirige el navegador a ella. `CustomerPortal` acepta las mismas opciones `bearerToken` y `environment` que `Checkout`.
El controlador no comprueba quién lo está llamando. Cualquiera que lo solicite con un ID de cliente obtiene el portal de ese cliente. Protege la ruta con tu propia autenticación y pasa únicamente el ID de cliente del usuario que ha iniciado sesión.
### Parámetros de consulta
El ID de cliente de la sesión del portal, por ejemplo `?customer_id=cus_123`.
Si se establece en `true`, Dodo Payments también envía por correo electrónico el enlace del portal al cliente.
El controlador devuelve 400 si falta `customer_id` y 500 si no se puede crear la sesión del portal.
## Controlador de rutas de webhook
El controlador de rutas de webhook verifica cada solicitud con tu secreto de webhook, que se pasa como `webhookKey`, antes de ejecutar tu código:
* **Método:** Solo se admiten solicitudes POST. Los demás métodos devuelven 405.
* **Verificación de firma:** Verifica los encabezados `webhook-id`, `webhook-timestamp` y `webhook-signature` con `webhookKey`, siguiendo la especificación Standard Webhooks. Devuelve 401 si la verificación falla.
* **Validación de payload:** Valida el payload con Zod. Devuelve 400 si el payload no es válido.
* **Gestión de errores:**
* 401: Firma no válida
* 400: Payload no válido
* 500: Error interno durante la verificación
* **Enrutamiento de eventos:** Llama a `onPayload` para cada evento, después al controlador correspondiente al tipo de evento y devuelve 200.
El adaptador no captura los errores que se producen en tus controladores. Estos se propagan a TanStack Start y la solicitud falla.
### Controladores de eventos de webhook compatibles
Todos los controladores son opcionales y asíncronos, y reciben el payload verificado correspondiente a su tipo de evento:
```typescript TypeScript expandable theme={null}
onPayload?: (payload: WebhookPayload) => Promise;
onPaymentSucceeded?: (payload: WebhookPayload) => Promise;
onPaymentFailed?: (payload: WebhookPayload) => Promise;
onPaymentProcessing?: (payload: WebhookPayload) => Promise;
onPaymentCancelled?: (payload: WebhookPayload) => Promise;
onRefundSucceeded?: (payload: WebhookPayload) => Promise;
onRefundFailed?: (payload: WebhookPayload) => Promise;
onDisputeOpened?: (payload: WebhookPayload) => Promise;
onDisputeExpired?: (payload: WebhookPayload) => Promise;
onDisputeAccepted?: (payload: WebhookPayload) => Promise;
onDisputeCancelled?: (payload: WebhookPayload) => Promise;
onDisputeChallenged?: (payload: WebhookPayload) => Promise;
onDisputeWon?: (payload: WebhookPayload) => Promise;
onDisputeLost?: (payload: WebhookPayload) => Promise;
onSubscriptionActive?: (payload: WebhookPayload) => Promise;
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise;
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise;
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise;
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise;
onSubscriptionFailed?: (payload: WebhookPayload) => Promise;
onSubscriptionExpired?: (payload: WebhookPayload) => Promise;
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise;
onSubscriptionPaused?: (payload: WebhookPayload) => Promise;
onSubscriptionUnpaused?: (payload: WebhookPayload) => Promise;
onSubscriptionUpdatePaymentMethod?: (payload: WebhookPayload) => Promise;
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise;
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise;
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise;
onDunningStarted?: (payload: WebhookPayload) => Promise;
onDunningRecovered?: (payload: WebhookPayload) => Promise;
onCreditAdded?: (payload: WebhookPayload) => Promise;
onCreditDeducted?: (payload: WebhookPayload) => Promise;
onCreditExpired?: (payload: WebhookPayload) => Promise;
onCreditRolledOver?: (payload: WebhookPayload) => Promise;
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise;
onCreditOverageCharged?: (payload: WebhookPayload) => Promise;
onCreditOverageReset?: (payload: WebhookPayload) => Promise;
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise;
onCreditBalanceLow?: (payload: WebhookPayload) => Promise;
onEntitlementGrantCreated?: (payload: WebhookPayload) => Promise;
onEntitlementGrantDelivered?: (payload: WebhookPayload) => Promise;
onEntitlementGrantFailed?: (payload: WebhookPayload) => Promise;
onEntitlementGrantRevoked?: (payload: WebhookPayload) => Promise;
onPayoutCreated?: (payload: WebhookPayload) => Promise;
onPayoutOnHold?: (payload: WebhookPayload) => Promise;
onPayoutInProgress?: (payload: WebhookPayload) => Promise;
onPayoutFailed?: (payload: WebhookPayload) => Promise;
onPayoutSuccess?: (payload: WebhookPayload) => Promise;
```
Para saber qué significa cada evento, consulta la [Guía de eventos de webhook](/developer-resources/webhooks/intents/webhook-events-guide).
## Prompt para LLM
Copia este prompt en tu asistente de programación con IA para que añada el adaptador a tu proyecto. Para proporcionar también a tu agente la documentación y las skills de Dodo Payments, instala el [Agent Plugin](/developer-resources/build-with-ai-coding-agents).
```text expandable theme={null}
You are an expert TanStack developer assistant. Your task is to guide a user through integrating the @dodopayments/tanstack adapter into their existing TanStack Start project.
The @dodopayments/tanstack adapter provides request handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities. Each handler takes a Request and returns a Response, so call it from a TanStack Start server route.
First, install the necessary packages. Use the package manager appropriate for your project (npm, yarn, or bun) based on the presence of lock files (e.g., package-lock.json for npm, yarn.lock for yarn, bun.lockb for bun):
npm install @dodopayments/tanstack
The examples below define server routes with createFileRoute and server.handlers. If the project uses an older TanStack Start release that exports createServerFileRoute from @tanstack/react-start/server instead, use createServerFileRoute("/api/checkout").methods({ GET, POST }) with the same handler bodies.
Here's how you should structure your response:
Ask the user which functionalities they want to integrate.
"Which parts of the @dodopayments/tanstack adapter would you like to integrate into your project? You can choose one or more of the following:
Checkout Route Handler (for handling product checkouts)
Customer Portal Route Handler (for managing customer subscriptions/details)
Webhook Route Handler (for receiving Dodo Payments webhook events)
All (integrate all three)"
Based on the user's selection, provide detailed integration steps for each chosen functionality.
If Checkout Route Handler is selected:
Purpose: This handler manages different types of checkout flows. All checkout types (static, dynamic, and sessions) return JSON responses with checkout URLs for programmatic handling.
File Creation: Create a new file at src/routes/api/checkout.ts in your TanStack Start project.
Code Snippet:
// src/routes/api/checkout.ts
import { Checkout } from "@dodopayments/tanstack";
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/api/checkout")({
server: {
handlers: {
GET: async ({ request }) => {
return Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
type: "static", // optional, defaults to 'static'
})(request);
},
POST: async ({ request }) => {
return Checkout({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
type: "session", // or "dynamic" for dynamic link
})(request);
},
},
},
});
Configuration & Usage:
bearerToken: Your Dodo Payments API key. It's recommended to set this via the DODO_PAYMENTS_API_KEY environment variable.
returnUrl: (Optional) The URL to redirect the user to after a successful checkout. A return_url in the POST body takes precedence.
environment: (Optional) Set to "test_mode" for testing, or omit/set to "live_mode" for production.
type: (Optional) Set to "static" for GET/static checkout, "dynamic" for POST/dynamic checkout, or "session" for POST/checkout sessions.
Static Checkout (GET) Query Parameters:
productId (required): Product identifier (e.g., ?productId=pdt_nZuwz45WAs64n3l07zpQR)
quantity (optional): Quantity of the product
Customer Fields (optional): fullName, firstName, lastName, email, country, addressLine, city, state, zipCode
Disable Flags (optional, set to true to disable): disableFullName, disableFirstName, disableLastName, disableEmail, disableCountry, disableAddressLine, disableCity, disableState, disableZipCode
Advanced Controls (optional): paymentCurrency, showCurrencySelector, paymentAmount, showDiscounts
Metadata (optional): Any query parameter starting with metadata_ (e.g., ?metadata_userId=abc123)
Returns: {"checkout_url": "https://test.checkout.dodopayments.com/buy/pdt_nZuwz45WAs64n3l07zpQR?quantity=1"}
Dynamic Checkout (POST) - Returns JSON with checkout_url: Parameters are sent as a JSON body. It requires billing and customer, plus product_id or product_cart. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://test.checkout.dodopayments.com/cbq"}. For a complete list of supported POST body fields, refer to:
Docs - One Time Payment Product: https://docs.dodopayments.com/api-reference/payments/post-payments
Docs - Subscription Product: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions
Checkout Sessions (POST) - (Recommended) A more customizable checkout experience. Returns JSON with checkout_url: Parameters are sent as a JSON body, and product_cart is required. Supports both one-time and recurring payments. Returns: {"checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"}. For a complete list of supported fields, refer to:
Checkout Sessions Integration Guide: https://docs.dodopayments.com/developer-resources/checkout-session
Error Handling: If productId is missing or other query parameters are invalid, the handler will return a 400 response.
If Customer Portal Route Handler is selected:
Purpose: This handler redirects a customer to their Dodo Payments customer portal. It does not authenticate the caller, so protect the route and pass only the signed-in user's customer ID.
File Creation: Create a new file at src/routes/api/customer-portal.ts in your TanStack Start project.
Code Snippet:
// src/routes/api/customer-portal.ts
import { CustomerPortal } from "@dodopayments/tanstack";
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/api/customer-portal")({
server: {
handlers: {
GET: async ({ request }) => {
return CustomerPortal({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
})(request);
},
},
},
});
Query Parameters:
customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)
send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.
Returns 400 if customer_id is missing.
If Webhook Route Handler is selected:
Purpose: This handler processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
File Creation: Create a new file at src/routes/api/webhook.ts in your TanStack Start project.
Code Snippet:
// src/routes/api/webhook.ts
import { Webhooks } from "@dodopayments/tanstack";
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/api/webhook")({
server: {
handlers: {
POST: async ({ request }) => {
return Webhooks({
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY!,
onPayload: async (payload) => {
console.log(payload);
},
})(request);
},
},
},
});
Handler Details:
Method: Only POST requests are supported. Other methods return 405.
Signature Verification: The handler verifies the webhook signature using the webhookKey and returns 401 if verification fails.
Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.
Error Handling:
401: Invalid signature
400: Invalid payload
500: Internal error during verification
Event Routing: Calls onPayload for every event, then the event handler that matches the payload type.
Supported Webhook Event Handlers:
onPayload?: (payload: WebhookPayload) => Promise
onPaymentSucceeded?: (payload: WebhookPayload) => Promise
onPaymentFailed?: (payload: WebhookPayload) => Promise
onPaymentProcessing?: (payload: WebhookPayload) => Promise
onPaymentCancelled?: (payload: WebhookPayload) => Promise
onRefundSucceeded?: (payload: WebhookPayload) => Promise
onRefundFailed?: (payload: WebhookPayload) => Promise
onDisputeOpened?: (payload: WebhookPayload) => Promise
onDisputeExpired?: (payload: WebhookPayload) => Promise
onDisputeAccepted?: (payload: WebhookPayload) => Promise
onDisputeCancelled?: (payload: WebhookPayload) => Promise
onDisputeChallenged?: (payload: WebhookPayload) => Promise
onDisputeWon?: (payload: WebhookPayload) => Promise
onDisputeLost?: (payload: WebhookPayload) => Promise
onSubscriptionActive?: (payload: WebhookPayload) => Promise
onSubscriptionOnHold?: (payload: WebhookPayload) => Promise
onSubscriptionRenewed?: (payload: WebhookPayload) => Promise
onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise
onSubscriptionCancelled?: (payload: WebhookPayload) => Promise
onSubscriptionFailed?: (payload: WebhookPayload) => Promise
onSubscriptionExpired?: (payload: WebhookPayload) => Promise
onSubscriptionUpdated?: (payload: WebhookPayload) => Promise
onSubscriptionPaused?: (payload: WebhookPayload) => Promise
onSubscriptionUnpaused?: (payload: WebhookPayload) => Promise
onSubscriptionUpdatePaymentMethod?: (payload: WebhookPayload) => Promise
onLicenseKeyCreated?: (payload: WebhookPayload) => Promise
onAbandonedCheckoutDetected?: (payload: WebhookPayload) => Promise
onAbandonedCheckoutRecovered?: (payload: WebhookPayload) => Promise
onDunningStarted?: (payload: WebhookPayload) => Promise
onDunningRecovered?: (payload: WebhookPayload) => Promise
onCreditAdded?: (payload: WebhookPayload) => Promise
onCreditDeducted?: (payload: WebhookPayload) => Promise
onCreditExpired?: (payload: WebhookPayload) => Promise
onCreditRolledOver?: (payload: WebhookPayload) => Promise
onCreditRolloverForfeited?: (payload: WebhookPayload) => Promise
onCreditOverageCharged?: (payload: WebhookPayload) => Promise
onCreditOverageReset?: (payload: WebhookPayload) => Promise
onCreditManualAdjustment?: (payload: WebhookPayload) => Promise
onCreditBalanceLow?: (payload: WebhookPayload) => Promise
onEntitlementGrantCreated?: (payload: WebhookPayload) => Promise
onEntitlementGrantDelivered?: (payload: WebhookPayload) => Promise
onEntitlementGrantFailed?: (payload: WebhookPayload) => Promise
onEntitlementGrantRevoked?: (payload: WebhookPayload) => Promise
onPayoutCreated?: (payload: WebhookPayload) => Promise
onPayoutOnHold?: (payload: WebhookPayload) => Promise
onPayoutInProgress?: (payload: WebhookPayload) => Promise
onPayoutFailed?: (payload: WebhookPayload) => Promise
onPayoutSuccess?: (payload: WebhookPayload) => Promise
Environment Variable Setup:
To ensure the adapter functions correctly, you will need to manually set up the following environment variables in your TanStack project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):
DODO_PAYMENTS_API_KEY: Your Dodo Payments API Key (required for Checkout and Customer Portal).
DODO_PAYMENTS_RETURN_URL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).
DODO_PAYMENTS_WEBHOOK_KEY: Your Dodo Payments Webhook Secret (required for Webhook handler).
DODO_PAYMENTS_ENVIRONMENT: test_mode or live_mode. The handlers default to live_mode.
Example .env file:
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
Usage in your code:
bearerToken: process.env.DODO_PAYMENTS_API_KEY
webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY!
Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.
If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance. You can also add comments to their PR or chat depending on the context
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.