Skip to main content
Para que tu agente de programación escriba la integración, instala el Dodo Agent Plugin. Añade las skills y los servidores MCP de Dodo Payments a Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro y OpenCode.
Crearás MailKit, un servicio de correo electrónico transaccional en el que los clientes pagan por adelantado créditos de correo. Un plan mensual concede 5.000 correos por ciclo de facturación. Si a un cliente le quedan pocos créditos, compra un paquete de recarga en lugar de esperar al siguiente ciclo. Cada envío descuenta un crédito.
Este tutorial usa Resend como proveedor de correo electrónico. Su nivel gratuito (3.000 correos al mes) cubre la creación y las pruebas de todo el flujo. El patrón de facturación funciona con cualquier proveedor: reemplaza resend.emails.send por una llamada a SendGrid, Postmark, Amazon SES o tu propio relay SMTP.
Al terminar, sabrás cómo:
  • Crear un entitlement de crédito personalizado para correos en el dashboard.
  • Vincular créditos a un plan de suscripción y a un producto de recarga de compra única.
  • Enviar correos mediante Resend y descontar un crédito por envío con una entrada en el ledger.
  • Leer el saldo de créditos actualizado de un cliente desde tu frontend.
  • Verificar los webhooks de Dodo Payments y gestionar credit.balance_low para avisar a los clientes antes de que su saldo llegue a cero.

Lo que vamos a crear

MailKit vende dos productos: La unidad es un correo = un crédito. Los clientes no necesitan pensar en tokens, lotes ni unidades ponderadas. Ven “quedan 4.231 correos este mes”. Antes de comenzar, necesitas:
  • Una cuenta de Dodo Payments. Crea todo en modo de prueba.
  • Una cuenta gratuita de Resend y una API key.
  • Node.js 22 o posterior y conocimientos prácticos de TypeScript.

Paso 1: Crea tu entitlement de crédito para correos

El entitlement de crédito define la unidad que vende MailKit: un envío de correo.
Pestaña Credits dentro de Products, con los entitlements de crédito de la empresa

The Credits tab under Products lists all your credit entitlements.

1

Open the Credits Section

  1. Inicia sesión en el dashboard de Dodo Payments.
  2. Haz clic en Products en la barra lateral.
  3. Selecciona la pestaña Credits.
  4. Haz clic en Create Credit.
2

Configure the Credit Unit

Introduce estos valores:Credit Name: Email CreditsCredit Type: Custom UnitUnit Name: emailDefine Precision: 0. Un correo es una unidad entera, por lo que el saldo nunca necesita decimales.Credit Expiry: 30 days. Los créditos no utilizados caducan 30 días después de emitirse.
La precisión no se puede cambiar después de crear el crédito. Para unidades discretas como correos, mensajes o sesiones, usa 0.
3

Leave the Other Defaults

Este tutorial mantiene desactivados el rollover y el overage para que el flujo de créditos sea mínimo. Puedes activarlos más adelante, ya sea en el crédito o en el vínculo de crédito de cada producto.
4

Save and Copy the Credit ID

Haz clic en Create Credit. Abre el crédito y copia su ID, que comienza por cde_. El backend lo usa para leer saldos y crear entradas en el ledger.
El entitlement Email Credits está listo. A continuación, crea los productos que lo conceden a los clientes.

Paso 2: Crea el plan y el paquete de recarga

Crea dos productos que vinculen el mismo entitlement Email Credits: un plan de Subscription que concede 5.000 correos en cada ciclo de facturación y una recarga One Time que añade otros 5.000 bajo demanda.
Este tutorial descuenta créditos con entradas en el ledger en lugar de usar medidores de uso. El débito del ledger se aplica cuando la llamada a la API devuelve la respuesta, no requiere configurar un medidor y se adapta a casos en los que una acción del usuario cuesta exactamente un crédito. Para descontar créditos automáticamente a partir de eventos de uso ingeridos, lo que resulta adecuado para unidades ponderadas como tokens o megabytes procesados, consulta Usage Billing with Credits en la guía de Credit-Based Billing.

Plan MailKit ($19/mes, 5.000 correos)

1

Create the Subscription

  1. Ve a Products y haz clic en Add Product.
  2. Introduce los detalles del producto:
Product Name: MailKit PlanDescription: 5,000 transactional emails per month.
  1. En Pricing Type, selecciona Subscription.
  2. Define el precio recurrente:
Price: 19.00Repeat payment every: 1 mesCurrency: USD
2

Attach the Email Credit Entitlement

En la sección Entitlements, haz clic en Attach junto a Credits y configura:Select credits: Email CreditsCredits issued per billing cycle: 5000Low Balance Threshold (%): 20. Dodo Payments envía credit.balance_low cuando el saldo cae por debajo del 20 % de los créditos emitidos por ciclo, es decir, 1.000 correos.Import Default Credit Settings: activado, para que el producto use la caducidad de 30 días del Paso 1.Añade el crédito al producto y, después, guarda el producto. Copia el ID del producto, que comienza por pdt_.
Plan: $19/mes, con 5.000 correos emitidos en cada ciclo de facturación.

Paquete de recarga ($9 por compra única, 5.000 correos)

1

Create a One-Time Product

  1. Ve a Products y haz clic en Add Product.
  2. Introduce los detalles del producto:
Product Name: Email Top-Up PackDescription: Add 5,000 emails to your MailKit balance.
  1. En Pricing Type, selecciona One Time.
  2. Define el precio:
Price: 9.00Currency: USD
2

Attach the Credit Grant

En la sección Entitlements, haz clic en Attach junto a Credits y configura:
  • Select credits: Email Credits
  • No of credits issued: 5000
Un producto de compra única concede créditos con su propia caducidad: 30 días desde la compra, según el valor predeterminado que configuraste en el Paso 1. Los créditos de recarga se suman a los créditos de la suscripción; no los reemplazan.
Guarda el producto y copia su ID.
Paquete de recarga: $9 por 5.000 correos, añadidos al saldo cuando el pago se completa correctamente.

Paso 3: Configura el backend

Crea el servidor Express que genere checkouts, envíe correos, lea saldos y reciba webhooks.
1

Initialize the Project

Añade un script de desarrollo a package.json:
tsx ejecuta TypeScript directamente, sin un paso de compilación ni un tsconfig.json. Para producción, añade un tsconfig.json y un script build.
2

Configure Environment Variables

Crea .env con una API key de modo de prueba de Developer → API Keys y los IDs de los Pasos 1 y 2:
.env
Completarás DODO_PAYMENTS_WEBHOOK_KEY en el Paso 4, después de crear el endpoint del webhook. Crea la API key de Resend en resend.com/api-keys.
Añade .env a .gitignore antes de tu primer commit. Nunca hagas commit de API keys.
3

Build the Server

Crea server.ts en la raíz del proyecto. El servidor expone cinco rutas: checkout de suscripción, checkout de recarga, lectura de saldo, envío y receptor del webhook.
La ruta del webhook debe recibir el cuerpo sin procesar de la solicitud. express.json() reemplaza el cuerpo por un objeto analizado, y la verificación de firma necesita los bytes exactos que firmó Dodo Payments. Mantén la ruta /webhooks/dodo, con express.raw(), encima de la línea app.use(express.json()).
El backend está listo: suscripción, recarga, saldo, envío y el handler del webhook.
4

Add a Demo UI

Crea public/index.html. Llama a cada ruta desde un formulario sencillo para que puedas probar el flujo en un navegador:

Paso 4: Conecta el endpoint del webhook

El evento credit.balance_low permite avisar a los clientes antes de que se queden sin créditos. Sin él, un cliente detectaría el problema cuando un correo no pudiera enviarse.
1

Expose Your Local Server

Los webhooks necesitan una URL pública. Durante el desarrollo, usa ngrok u otro túnel:
Copia la URL de reenvío HTTPS, por ejemplo https://1234abcd.ngrok-free.app.
2

Register the Endpoint in Dodo Payments

  1. Ve a Developer → Webhooks y haz clic en Add endpoint.
  2. Introduce la URL https://1234abcd.ngrok-free.app/webhooks/dodo usando el host de tu propio túnel.
  3. Selecciona los eventos credit.added, credit.balance_low y credit.rolled_over.
  4. Haz clic en Create endpoint.
  5. Copia el signing secret de la pestaña Overview del endpoint en .env como DODO_PAYMENTS_WEBHOOK_KEY.
  6. Reinicia el servidor.

Paso 5: Prueba el flujo completo

1

Start the Server

El servidor registra MailKit running on http://localhost:3000. Abre esa URL en tu navegador.
2

Subscribe a Test Customer

  1. En la sección 1, introduce una dirección de correo y un nombre de prueba, y haz clic en Get checkout link.
  2. Abre el enlace y completa el checkout con una test card.
  3. En el dashboard, ve a Customers y copia el ID del nuevo cliente, que comienza por cus_.
El cliente tiene 5.000 correos en su saldo. Para confirmarlo, abre el cliente en Customers y selecciona la pestaña Credits.
3

Send an Email

  1. Pega el ID del cliente en la sección 3.
  2. Deja To establecido en delivered@resend.dev, una dirección de prueba de Resend que acepta todos los mensajes.
  3. Haz clic en Send.
La página muestra el ID del mensaje de Resend. Actualiza el saldo en la sección 2: indica 4.999. El débito del ledger forma parte del saldo en cuanto la llamada a la API devuelve la respuesta.
4

Trigger the Low-Balance Webhook

El umbral es del 20 %, es decir, 1.000 de los 5.000 correos emitidos por ciclo. Para alcanzarlo sin enviar 4.000 correos, descuenta el saldo manualmente en el dashboard:
  1. Abre el cliente en Customers, selecciona la pestaña Credits y elige Email Credits.
  2. Haz clic en Apply Credit/Debit, selecciona Debit e introduce 4000. El saldo ahora es exactamente 1.000, por lo que todavía no está por debajo del umbral.
  3. Envía otro correo desde la demo. El saldo baja a 999.
Cuando llega el webhook, el servidor registra:
El servidor recibió y verificó el webhook. En producción, aquí es donde enviarías un correo al cliente o mostrarías un banner dentro de la aplicación.
5

Buy a Top-Up Pack

  1. Pega el ID del cliente en la sección 4.
  2. Haz clic en Buy 5,000 emails y completa el checkout de prueba.
  3. Actualiza el saldo. Aumenta en 5.000.
Dodo Payments envía un evento credit.added con transaction_type: "credit_added". El grant que hay detrás tiene source_type: one_time, que puedes leer de nuevo con la API List Customer Grants. Los créditos de recarga se suman a los créditos de la suscripción. Los débitos se extraen del grant que caduca primero y del grant más antiguo cuando dos caducan al mismo tiempo.
6

Test the Hard Stop

Descuenta el saldo hasta cero en el dashboard y, después, intenta enviar otro correo. El servidor responde con 402:
Ese 402 es la aplicación de la política de tu aplicación. Trata la API de saldo de Dodo Payments como la fuente de verdad y no almacenes en caché el saldo en el cliente.

Solución de problemas

La firma cubre el cuerpo HTTP sin procesar. express.json() reemplaza el cuerpo por un objeto analizado, por lo que la verificación falla. Registra /webhooks/dodo con express.raw({ type: 'application/json' }) encima de la línea app.use(express.json()). Después, comprueba que DODO_PAYMENTS_WEBHOOK_KEY coincida con el signing secret de la pestaña Overview del endpoint.
Comprueba estas tres cosas, en orden:
  1. El cliente completó el checkout. Los créditos se emiten cuando el pago se completa correctamente, no cuando se crea la sesión de checkout.
  2. CREDIT_ENTITLEMENT_ID en .env coincide con el crédito vinculado al producto. Las llamadas de saldo y ledger usan este ID, por lo que una discrepancia lee o descuenta de un crédito diferente.
  3. El customer_id que pasas es el ID de cliente de Dodo Payments (comienza por cus_), no un ID de tu propia base de datos.
El remitente de prueba onboarding@resend.dev solo entrega mensajes a la dirección de correo de tu cuenta de Resend o a delivered@resend.dev. Para enviar mensajes a cualquier otra persona, verifica un dominio y usa una dirección from en ese dominio.

Lo que has creado

One Reusable Credit Unit

Email Credits, definido una sola vez y vinculado tanto al plan de suscripción como al paquete de recarga.

Subscription with Prepaid Allowance

$19/mes concede 5.000 correos por ciclo de facturación. Los clientes saben por qué pagan y tú conoces tu coste máximo.

Top-Up Pack

Un producto de compra única que concede 5.000 correos además de los créditos de la suscripción, sin cambiar el plan.

Direct Ledger Debits

Una llamada a createLedgerEntry después de cada envío, sin medidor ni retraso de agregación. El ID del mensaje de Resend como clave de idempotencia evita un segundo débito para el mismo envío.

Credit-Based Billing Reference

Rollover, modos de overage, gestión del ledger y la API completa de créditos.
Para obtener ayuda, pregunta en la Discord Community o escribe a support@dodopayments.com.
Última modificación el 26 de septiembre de 2026