Skip to main content
Para que tu agente de programación escriba la integración, instala el Dodo Agent Plugin. Añade las habilidades y los servidores MCP de Dodo Payments a Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro y OpenCode.
Crearás NeuralAPI, una API de IA escalonada en la que cada plan de suscripción incluye una asignación mensual de créditos de tokens. Los clientes que se quedan sin créditos compran un paquete de recarga, y tu backend informa de los tokens utilizados por cada solicitud a OpenAI para que Dodo Payments los descuente del saldo del cliente.
Este tutorial utiliza Node.js, Express y el SDK de OpenAI. Los conceptos de Dodo Payments (créditos, medidores y webhooks) funcionan de la misma manera con cualquier framework o proveedor de IA.
Al terminar, sabrás cómo:
  • Crear un derecho de crédito personalizado para tokens y un medidor que lo descuente.
  • Asociar créditos a planes de suscripción, con y sin exceso de uso, y a un producto de recarga de un solo pago.
  • Llamar a OpenAI desde un endpoint que factura los tokens mediante Dodo Payments.
  • Leer el saldo de créditos actualizado de un cliente con el SDK.
  • Verificar firmas de webhooks y dirigir los eventos de crédito de Dodo Payments.

Lo que vamos a crear

NeuralAPI vende tres productos: Antes de empezar, necesitas:
  • Una cuenta de Dodo Payments. Realiza todo en modo de prueba.
  • Una clave de API de OpenAI.
  • Node.js 22 o posterior, y conocimientos prácticos de TypeScript y Node.js.

Paso 1: Crear el derecho de crédito de tokens

Crea el derecho de crédito que compartirán ambos planes y el paquete de recarga. Define la unidad de tokens que vende NeuralAPI.
Página de listado de créditos que muestra los derechos de crédito creados

The Credits tab under Products shows all your credit entitlements.

1

Navigate to Credits

  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: API TokensCredit Type: Custom UnitUnit Name: tokenDefine Precision: 0. Los recuentos de tokens son números enteros.Credit Expiry: 30 days. Los créditos caducan 30 días después de su emisión, lo que coincide con el ciclo de facturación mensual.
La precisión no se puede cambiar después de crear el crédito. Para los recuentos de tokens, utiliza 0.
3

Skip Overage at the Credit Level

Deja el exceso de uso desactivado en el crédito. Lo configurarás por plan al asociar el crédito a cada producto, de modo que el plan Starter pueda bloquear el uso al llegar a cero, mientras que el plan Pro permita exceso de uso.
La configuración de exceso de uso del crédito es la predeterminada. Cada asociación de producto puede sobrescribirla, como hace el paso 3 con el plan Pro.
4

Save and Copy the Credit ID

Haz clic en Create Credit. Abre el crédito guardado y copia su ID, que comienza por cde_.
El derecho de crédito API Tokens está listo. A continuación, crea un medidor para que los eventos de uso descuenten créditos.

Paso 2: Crear un medidor para el uso de tokens

Un medidor agrega los eventos de uso entrantes. Cuando lo vinculas a un crédito, el uso agregado se descuenta del saldo de créditos del cliente. Crea el medidor antes que los productos de planes, porque lo asociarás mientras los creas en el paso 3.
1

Open the Meters Section

  1. En la barra lateral del dashboard, ve a Products → Meters.
  2. Haz clic en Create Meter.
2

Configure the Meter

Introduce estos valores:Meter Name: Token Usage MeterEvent Name: api.tokens_used. Debe coincidir con event_name, que envía tu aplicación.Aggregation Type: Sum, para sumar el recuento de tokens de cada evento.Over Property: tokens, la clave de metadatos cuyo valor se suma.Measurement Unit: tokens
Los nombres de eventos distinguen entre mayúsculas y minúsculas: api.tokens_used e Api.Tokens.Used son eventos diferentes. No puedes editar un medidor después de crearlo, así que comprueba todos los valores antes de confirmarlo.
Crea el medidor. Lo seleccionarás por nombre al asociarlo a los productos.
El medidor está creado. A continuación, vincúlalo al crédito de cada producto de plan.

Paso 3: Crear los productos de los planes

Crea ambos planes con el tipo de precio Usage Based Billing, no con Subscription simple. Los medidores se asocian a productos de Usage Based Billing, y el medidor es el que descuenta créditos cuando los clientes llaman a tu API. Un producto de Usage Based Billing sigue cobrando una tarifa base recurrente ($29 o $99), y el uso adicional se factura en créditos.
Configuración de precios de Usage Based Billing

Usage Based Billing pricing type with meter configuration.

Starter Plan ($29/mes — 10M tokens, sin exceso de uso)

1

Create the Starter Product

  1. Ve a Products y haz clic en Add Product.
  2. En Pricing Type, selecciona Usage Based Billing.
  3. Introduce estos valores:
Product Name: NeuralAPI StarterDescription: 10 million API tokens per month. Perfect for individual developers and small projects.Price: 29.00. Esta es la tarifa base recurrente, que se cobra cada mes incluso antes de cualquier uso.Repeat payment every: 1 mesCurrency: USD
2

Attach the Meter

En la sección Select meter, haz clic en + y añade Token Usage Meter. Después configura el medidor:
  1. Activa Bill usage in credits.
  2. Select credit: API Tokens
  3. Meter units per credit: 1. Cada token de un evento descuenta un crédito.
  4. Free Threshold: 0. El umbral gratuito solo se aplica cuando un medidor factura dinero. Cuando factura créditos, cada unidad se descuenta del saldo.
Medidor con Bill usage in Credits activado y API Tokens seleccionado

Toggle 'Bill usage in Credits' on the meter and pick the credit entitlement.

Esta asociación hace que los eventos entrantes api.tokens_used descuenten del saldo del cliente.
3

Configure Credit Issuance for Starter

Después de asociar un medidor facturado en créditos, el producto muestra una sección de configuración de créditos. Introduce:Credits issued per billing cycle: 10000000Import Default Credit Settings: activado, para que el producto utilice la caducidad de 30 días del derecho de crédito.Allow Overage: desactivado. El valor predeterminado del paso 1 mantiene desactivado el exceso de uso, por lo que los clientes Starter se detienen al llegar a cero.
Formulario de configuración de créditos con cantidad por ciclo y ajustes de exceso de uso

Configure credit issuance per cycle on the UBB product.

Guarda el producto y copia su ID, que comienza por pdt_.
Starter Plan: tarifa base de $29/mes, 10M tokens por ciclo, bloqueado en cero y descontado mediante el medidor.

Pro Plan ($99/mes — 40M tokens, exceso de uso activado)

1

Create the Pro Product

Sigue el flujo de Starter con estos valores:Product Name: NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 mesCurrency: USD
2

Attach the Meter

Configura el medidor como hiciste para Starter: añade Token Usage Meter, activa Bill usage in credits, selecciona API Tokens y establece Meter units per credit en 1 y Free Threshold en 0.
3

Configure Credit Issuance with Overage

Configura la emisión de créditos, esta vez con el exceso de uso activado:Credits issued per billing cycle: 40000000Import Default Credit Settings: desactivado, para poder establecer el exceso de uso de este producto.Allow Overage: activadoPrice Per Unit: 0.000005 USD por token. Eso equivale a $0.005 por cada 1K tokens, o $5 por cada 1M tokens, un valor superior a la tarifa efectiva por token del plan que desincentiva el exceso de uso.Overage Behavior: Bill overage at billing. El exceso de uso se cobra en la siguiente factura y, después, el saldo se restablece.Guarda el producto y copia su ID.
Pro Plan: tarifa base de $99/mes, 40M tokens por ciclo, exceso de uso a $0.005 por cada 1K tokens y descuento mediante el medidor.

Paso 4: Crear el paquete de recarga de tokens

El paquete de recarga es una compra única que añade 5.000.000 tokens al saldo de un cliente existente.
Sección de precios del producto con Single Payment seleccionado

One-time pricing selected for a credit product.

1

Create a One-Time Product

  1. Ve a Products y haz clic en Add Product.
  2. En Pricing Type, selecciona One Time.
  3. Introduce estos valores:
Product Name: Token Top-Up PackDescription: Add 5 million tokens to your NeuralAPI balance.Price: 19.00Currency: USD
2

Attach the Token Credit

  1. En la sección Entitlements, haz clic en Attach junto a Credits.
  2. Selecciona API Tokens.
  3. Establece No of credits issued en 5000000.
  4. Desactiva Import Default Credit Settings para sobrescribir la caducidad predeterminada de 30 días.
  5. Establece Credit Expiry en Custom e introduce 365 días.
  6. Guarda el producto.
Copia el ID del producto.
¿Por qué una caducidad más larga para las recargas? Los créditos de suscripción caducan después de 30 días porque ese es el ciclo de facturación. Una recarga es una compra prepagada: el cliente pagó $19 por adelantado y espera que los tokens duren más de un mes. Una caducidad de 365 días coincide con el funcionamiento de los créditos de API prepagados en OpenAI y Anthropic, donde los créditos comprados caducan un año después de la compra, y aún limita tu responsabilidad para que los clientes no puedan acumular créditos indefinidamente.
El paquete de recarga está configurado. Al comprarlo, se otorgan 5.000.000 tokens válidos durante 365 días.

Paso 5: Crear el backend

Crea el servidor de Express. Este crea los checkouts de suscripción y de recarga, llama a OpenAI y factura los tokens, lee los saldos y recibe eventos de crédito mediante webhooks.
1

Set Up Your Project

Crea un tsconfig.json:
tsconfig.json
Actualiza los scripts de package.json:
package.json
2

Set Up Environment Variables

Crea .env con una clave de API de modo de prueba de Developer → API Keys y los IDs de los pasos anteriores:
.env
Nunca confirmes .env en el control de versiones. Añádelo a .gitignore antes de tu primer commit.
Completarás DODO_PAYMENTS_WEBHOOK_KEY en el paso 7, después de registrar el endpoint del webhook.
3

Implement the Server

Crea src/server.ts. El endpoint de completion llama al modelo gpt-6-luna de OpenAI, que es adecuado para solicitudes de gran volumen. La pestaña package.json muestra la lista completa de dependencias:
El backend está listo: checkout de suscripciones, checkout de recargas, una completion de OpenAI con facturación de tokens medida, una lectura del saldo y un handler de webhooks verificado.
@dodopayments/ingestion-blueprints proporciona trackers que realizan por ti la llamada usageEvents.ingest, incluido el uso de LLM Blueprint, API gateway, object storage, streams y time-range.
4

How Deductions Happen

El servidor nunca llama a un endpoint de “deducir N créditos”. El meter realiza la deducción:
  1. Tu handler llama a OpenAI y lee usage.total_tokens, por ejemplo 1532.
  2. Ingestas un evento de uso con event_name: api.tokens_used y metadata: { tokens: 1532 }.
  3. Token Usage Meter agrega los eventos por cliente. Un worker en segundo plano procesa los eventos nuevos cada minuto.
  4. Como el meter factura el crédito API Tokens mediante Bill usage in credits, Dodo Payments deduce 1532 créditos, comenzando por la asignación del cliente que caduca primero (FIFO).
  5. Si el exceso está habilitado y el saldo se agota, el déficit se registra y se factura en la siguiente invoice.
Tu código solo ingesta eventos.

Paso 6: Añade un frontend de demostración

Crea public/index.html para probar todos los flujos en tu navegador. La página guarda el ID del cliente en localStorage, de modo que suscribirse, generar y recargar compartan una misma identidad, como ocurriría en una aplicación con inicio de sesión:

Paso 7: Configura el webhook

Los webhooks permiten que tu servidor reaccione a los cambios de saldo, por ejemplo, para enviar un correo a un cliente cuyo saldo se está agotando.
1

Expose Your Local Server

Los webhooks necesitan una URL pública. Para el desarrollo local, usa ngrok u otro túnel:
Copia la URL de reenvío HTTPS, que termina en ngrok-free.app.
2

Register the Webhook in Dodo Payments

  1. En el dashboard, ve a Developer → Webhooks y haz clic en Add endpoint.
  2. Introduce la URL https://your-tunnel.ngrok-free.app/webhooks/dodo usando el host de tu propio túnel.
  3. Selecciona al menos estos eventos:
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. Haz clic en Create endpoint y copia el signing secret de la pestaña Overview del endpoint.
  5. Pégalo en .env como DODO_PAYMENTS_WEBHOOK_KEY y reinicia npm run dev.
El dodo.webhooks.unwrap() del SDK comprueba los headers webhook-id, webhook-timestamp y webhook-signature con tu signing secret y, después, analiza el payload. No escribas tu propia comprobación HMAC: Dodo Payments sigue Standard Webhooks, que firma id.timestamp.body, no solo el body.

Paso 8: Prueba el flujo completo

1

Subscribe a Test Customer

  1. Ejecuta npm run dev.
  2. Abre http://localhost:3000.
  3. Elige Pro, introduce un correo electrónico y un nombre de prueba, y haz clic en Get Checkout Link. Completa el checkout con datos de tarjeta de prueba.
  4. En el dashboard, ve a Customers, abre el cliente más reciente y copia su ID, que comienza por cus_.
  5. Pega el ID en el campo Logged-in customer ID de la demo y haz clic en Save.
El cliente tiene 40.000.000 de tokens. Haz clic en Refresh Balance para confirmarlo.
2

Generate an AI Response

Escribe un prompt y haz clic en Generate. El servidor llama a OpenAI, lee el total_tokens real, ingesta un evento de uso y devuelve la respuesta.
Un worker en segundo plano procesa los eventos de uso cada minuto, por lo que el saldo no disminuye de inmediato. Espera uno o dos minutos y vuelve a hacer clic en Refresh Balance. Que el saldo no cambie en la primera actualización no significa que la medición haya fallado.
3

Test the Top-Up Flow

Haz clic en Buy 5M Tokens — $19 y completa el checkout. Cuando el pago se complete, actualiza el saldo: aumenta en 5.000.000 de tokens y el registro del servidor muestra un evento credit.added.

Solución de problemas

Posibles causas:
  • El nombre del evento del meter no coincide con el event_name que envías. api.tokens_used distingue entre mayúsculas y minúsculas.
  • El meter no está vinculado al crédito API Tokens del producto. Abre la configuración del meter del producto y confirma que Bill usage in credits esté activado.
  • La clave metadata.tokens no coincide con Over Property del meter.
  • La asignación del cliente ha caducado. Comprueba el historial de créditos del cliente.
Qué debes comprobar:
  1. En Products → Meters, abre el meter y confirma que el vínculo del producto muestre el nombre del crédito asociado.
  2. Abre la pestaña Events del meter. Los eventos ingeridos aparecen allí incluso antes de cualquier deducción.
  3. Abre el cliente en Customers y selecciona la pestaña Credits. Las entradas del ledger aparecen en uno o dos minutos.
Posibles causas:
  • El cliente no ha completado el checkout. Los créditos solo se emiten después de un pago exitoso.
  • Estás consultando con el customer_id incorrecto. Usa el ID que comienza por cus_ del dashboard, no un ID de tu propia base de datos.
  • CREDIT_ENTITLEMENT_ID en .env no coincide con el crédito asociado al producto.
Qué debes comprobar: Abre el cliente en Customers y selecciona la pestaña Credits. Si no aparecen créditos, el crédito no estaba asociado al producto o el pago no se completó.
Posibles causas:
  • El exceso no está habilitado en la credit attachment del producto Pro. La configuración del crédito solo es un valor predeterminado.
  • El cliente tiene el plan Starter, no Pro.
  • Overage Limit está establecido en 0.
Qué debes comprobar: Edita el producto Pro, abre el crédito en Entitlements y confirma que Allow Overage esté activado y que Price Per Unit sea 0.000005 ($5 por cada millón de tokens). Comprueba los ceros iniciales: el campo acepta un precio por token, no por 1K tokens.
Posibles causas:
  • Orden del análisis del body: express.json() se ejecutó sobre /webhooks/dodo antes que express.raw(). El SDK necesita los bytes sin procesar de la solicitud, no JSON analizado.
  • DODO_PAYMENTS_WEBHOOK_KEY contiene el signing secret incorrecto.
  • Un proxy inverso reescribe los headers de la solicitud.
Qué debes comprobar: Confirma que la línea app.use('/webhooks/dodo', express.raw(...)) aparezca antes que app.use(express.json()) en server.ts.

¿Necesitas ayuda?

¡Enhorabuena! Has creado la facturación basada en créditos para NeuralAPI

NeuralAPI ahora factura en créditos desde el checkout hasta la deducción:

Token Credit Entitlement

Un crédito API Tokens reutilizable con una caducidad de 30 días, compartido por ambos planes y el paquete de recarga.

Tiered Plans, One Credit

Starter (10M de tokens, límite estricto) y Pro (40M de tokens más exceso), configurados por producto sin duplicar el crédito.

One-Time Top-Up Pack

Los clientes añaden 5M de tokens por $19 sin cambiar su suscripción.

Deduction Through a Meter

Los recuentos reales de tokens de OpenAI se ingesta como eventos y el meter deduce los créditos mediante FIFO sin seguimiento manual.

Live Balance API

El saldo actual, leído mediante el SDK, para controlar el acceso, mostrar el uso o advertir a los clientes en tu aplicación.

Verified Webhook Pipeline

Eventos del ledger de créditos (credit.added, credit.deducted, credit.overage_charged) enviados a través de un handler que verifica las firmas con el helper Standard Webhooks del SDK.
¿Vas a pasar a producción? Refuerza estos aspectos:
  • Añade autenticación a /credits/:customerId y /api/generate. Tal como están escritos, cualquiera puede llamarlos con cualquier ID de cliente. Autentica a los usuarios y busca su ID de cliente en el servidor.
  • Usa valores estables de event_id. El ejemplo utiliza Date.now() más una cadena aleatoria. En producción, usa el ID de tu solicitud para que los reintentos sean idempotentes: Dodo Payments ignora un evento cuyo event_id ya haya ingerido.
  • Guarda la relación entre el cliente y el usuario. Guarda customer_id en tu base de datos después del primer checkout, para que los usuarios no tengan que pegarlo manualmente.
  • Decide qué ocurre cuando termina una suscripción. Los créditos del plan permanecen en el ledger del cliente hasta que caducan 30 días después de su emisión, y los créditos de recarga siguen siendo válidos durante 365 días. El /api/generate del tutorial solo comprueba el saldo, no el estado de la suscripción, por lo que un cliente cancelado todavía puede usar sus tokens restantes. Este es el valor predeterminado más favorable para el cliente. Para un acceso más estricto, (a) escucha el webhook subscription.cancelled y controla /api/generate según el estado de la suscripción, o (b) cuando se cancele, carga los créditos no utilizados del plan mediante la API del ledger. Las cargas se descuentan de la asignación que caduca primero, por lo que los créditos del plan de 30 días se consumen antes que los créditos de recarga de 365 días.
  • Supervisa el dashboard de Usage Billing para detectar pronto las anomalías de medición.

Credit-Based Billing Reference

Prorrateo, modos de exceso, gestión del ledger y todos los endpoints de la API de créditos.

Credit Webhook Events

Esquemas de payload para cada evento de crédito que puede recibir tu servidor.
Última modificación el 26 de septiembre de 2026