Skip to main content
Para que seu agente de programação escreva a integração, instale o Dodo Agent Plugin. Ele adiciona as skills e os servidores MCP do Dodo Payments ao Claude Code, Codex CLI, Cursor, VS Code / GitHub Copilot, Kiro e OpenCode.
Você criará a NeuralAPI, uma API de IA em níveis na qual cada plano de assinatura inclui uma franquia mensal de créditos de tokens. Quando os clientes ficam com poucos créditos, compram um pacote de recarga, e seu backend informa os tokens usados por cada solicitação da OpenAI para que o Dodo Payments os deduza do saldo do cliente.
Este tutorial usa Node.js, Express e o OpenAI SDK. Os conceitos do Dodo Payments (créditos, medidores e webhooks) funcionam da mesma forma com qualquer framework ou provedor de IA.
Ao terminar, você saberá como:
  • Criar um entitlement de crédito personalizado para tokens e um medidor que faça deduções dele.
  • Associar créditos a planos de assinatura, com e sem excesso de uso, e a um produto de recarga avulsa.
  • Chamar a OpenAI a partir de um endpoint que cobra tokens por meio do Dodo Payments.
  • Ler o saldo de créditos atual de um cliente com o SDK.
  • Verificar assinaturas de webhook e encaminhar eventos de crédito do Dodo Payments.

O Que Estamos Construindo

A NeuralAPI vende três produtos: Antes de começar, você precisa de:
  • Uma conta do Dodo Payments. Faça tudo no modo de teste.
  • Uma chave de API da OpenAI.
  • Node.js 22 ou posterior e conhecimento prático de TypeScript e Node.js.

Etapa 1: criar o entitlement de crédito de tokens

Crie o entitlement de crédito que será compartilhado pelos dois planos e pelo pacote de recarga. Ele define a unidade de token vendida pela NeuralAPI.
Página de listagem de créditos mostrando entitlements de crédito criados

The Credits tab under Products shows all your credit entitlements.

1

Navigate to Credits

  1. Acesse o dashboard do Dodo Payments.
  2. Clique em Products na barra lateral.
  3. Selecione a aba Credits.
  4. Clique em Create Credit.
2

Configure the Credit Unit

Insira estes valores:Credit Name: API TokensCredit Type: Custom UnitUnit Name: tokenDefine Precision: 0. As contagens de tokens são números inteiros.Credit Expiry: 30 days. Os créditos expiram 30 dias após serem emitidos, o que corresponde ao ciclo de cobrança mensal.
A precisão não pode ser alterada depois que o crédito é criado. Para contagens de tokens, use 0.
3

Skip Overage at the Credit Level

Mantenha o excesso de uso desativado no crédito. Você o configura por plano ao associar o crédito a cada produto, permitindo que o plano Starter bloqueie o uso em zero enquanto o plano Pro permita excesso de uso.
As configurações de excesso de uso no crédito são padrões. Cada associação de produto pode substituí-las, como a Etapa 3 faz para o plano Pro.
4

Save and Copy the Credit ID

Clique em Create Credit. Abra o crédito salvo e copie seu ID, que começa com cde_.
O entitlement de crédito API Tokens está pronto. Agora, crie um medidor para que os eventos de uso deduzam créditos.

Etapa 2: criar um medidor para o uso de tokens

Um medidor agrega eventos de uso recebidos. Quando você o vincula a um crédito, o uso agregado é deduzido do saldo de créditos do cliente. Crie o medidor antes dos produtos de plano, pois você o associa ao criá-los na Etapa 3.
1

Open the Meters Section

  1. Na barra lateral do dashboard, acesse Products → Meters.
  2. Clique em Create Meter.
2

Configure the Meter

Insira estes valores:Meter Name: Token Usage MeterEvent Name: api.tokens_used. Isso deve corresponder ao event_name enviado pelo seu app.Aggregation Type: Sum, para somar a contagem de tokens de cada evento.Over Property: tokens, a chave de metadados cujo valor é somado.Measurement Unit: tokens
Os nomes dos eventos diferenciam maiúsculas de minúsculas: api.tokens_used e Api.Tokens.Used são eventos diferentes. Não é possível editar um medidor depois de criá-lo, portanto verifique todos os valores antes de confirmar.
Crie o medidor. Você o selecionará pelo nome ao associá-lo aos produtos.
O medidor foi criado. Agora, associe-o ao crédito em cada produto de plano.

Etapa 3: criar os produtos de plano

Crie os dois planos com o tipo de preço Usage Based Billing, não com Subscription simples. Os medidores são associados a produtos Usage Based Billing, e o medidor é o que deduz créditos conforme os clientes chamam sua API. Um produto Usage Based Billing ainda cobra uma tarifa base recorrente ($29 ou $99), e o uso adicional é cobrado em créditos.
Configuração de preços Usage Based Billing

Usage Based Billing pricing type with meter configuration.

Plano Starter ($29/mês — 10 milhões de tokens, sem excesso de uso)

1

Create the Starter Product

  1. Acesse Products e clique em Add Product.
  2. Em Pricing Type, selecione Usage Based Billing.
  3. Insira estes valores:
Product Name: NeuralAPI StarterDescription: 10 million API tokens per month. Perfect for individual developers and small projects.Price: 29.00. Esta é a tarifa base recorrente, cobrada todos os meses mesmo antes de qualquer uso.Repeat payment every: 1 mêsCurrency: USD
2

Attach the Meter

Na seção Select meter, clique em + e adicione Token Usage Meter. Em seguida, configure o medidor:
  1. Ative Bill usage in credits.
  2. Select credit: API Tokens
  3. Meter units per credit: 1. Cada token em um evento deduz um crédito.
  4. Free Threshold: 0. O limite gratuito só se aplica quando um medidor cobra em dinheiro. Quando cobra em créditos, cada unidade é deduzida do saldo.
Medidor com Bill usage in Credits ativado e API Tokens selecionado

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

É essa associação que faz com que os eventos api.tokens_used recebidos deduzam o saldo do cliente.
3

Configure Credit Issuance for Starter

Depois que você associa um medidor cobrado em créditos, o produto exibe uma seção de configuração de créditos. Insira:Credits issued per billing cycle: 10000000Import Default Credit Settings: ativado, para que o produto use a expiração de 30 dias do entitlement de crédito.Allow Overage: desativado. O padrão da Etapa 1 mantém o excesso de uso desativado, então os clientes Starter param em zero.
Formulário de configuração de crédito com quantidade por ciclo e configurações de excesso de uso

Configure credit issuance per cycle on the UBB product.

Salve o produto e copie seu ID, que começa com pdt_.
Plano Starter: tarifa base de $29/mês, 10 milhões de tokens por ciclo, bloqueado em zero e deduzido por meio do medidor.

Plano Pro ($99/mês — 40 milhões de tokens, excesso de uso ativado)

1

Create the Pro Product

Siga o fluxo do Starter com estes valores:Product Name: NeuralAPI ProDescription: 40 million API tokens per month with overage. Built for production applications.Price: 99.00Repeat payment every: 1 mêsCurrency: USD
2

Attach the Meter

Configure o medidor como fez para o Starter: adicione Token Usage Meter, ative Bill usage in credits, selecione API Tokens e defina Meter units per credit como 1 e Free Threshold como 0.
3

Configure Credit Issuance with Overage

Configure a emissão de créditos, desta vez com o excesso de uso ativado:Credits issued per billing cycle: 40000000Import Default Credit Settings: desativado, para que você possa definir o excesso de uso para este produto.Allow Overage: ativadoPrice Per Unit: 0.000005 USD por token. Isso corresponde a $0.005 por 1 mil tokens, ou $5 por 1 milhão de tokens, valor superior à taxa efetiva por token do plano e que desestimula o excesso de uso.Overage Behavior: Bill overage at billing. O excesso de uso é cobrado na próxima fatura e, depois, o saldo é redefinido.Salve o produto e copie seu ID.
Plano Pro: tarifa base de $99/mês, 40 milhões de tokens por ciclo, excesso de uso a $0.005 por 1 mil tokens e deduzido por meio do medidor.

Etapa 4: criar o pacote de recarga de tokens

O pacote de recarga é uma compra avulsa que adiciona 5.000.000 de tokens ao saldo de um cliente existente.
Seção de preços do produto com Single Payment selecionado

One-time pricing selected for a credit product.

1

Create a One-Time Product

  1. Acesse Products e clique em Add Product.
  2. Em Pricing Type, selecione One Time.
  3. Insira estes 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. Na seção Entitlements, clique em Attach ao lado de Credits.
  2. Selecione API Tokens.
  3. Defina No of credits issued como 5000000.
  4. Desative Import Default Credit Settings para substituir a expiração padrão de 30 dias.
  5. Defina Credit Expiry como Custom e insira 365 dias.
  6. Salve o produto.
Copie o ID do produto.
Por que um prazo de expiração mais longo para os top-ups? Os créditos de assinatura expiram após 30 dias porque esse é o ciclo de cobrança. Um top-up é uma compra pré-paga: o cliente pagou $19 antecipadamente e espera que os tokens durem mais de um mês. Um prazo de expiração de 365 dias corresponde à forma como os créditos de API pré-pagos funcionam na OpenAI e na Anthropic, onde os créditos adquiridos expiram um ano após a compra, e ainda limita sua responsabilidade para que os clientes não possam acumular créditos indefinidamente.
O Pacote de Recarga está configurado. Comprá-lo concede 5.000.000 de tokens válidos por 365 dias.

Etapa 5: criar o backend

Crie o servidor Express. Ele cria checkouts de assinatura e de recarga, chama a OpenAI e cobra os tokens, lê saldos e recebe eventos de crédito por webhook.
1

Set Up Your Project

Crie um tsconfig.json:
tsconfig.json
Atualize os scripts de package.json:
package.json
2

Set Up Environment Variables

Crie .env com uma chave de API do modo de teste em Developer → API Keys e os IDs das etapas anteriores:
.env
Nunca faça commit de .env no controle de versão. Adicione-o a .gitignore antes do primeiro commit.
Você preencherá DODO_PAYMENTS_WEBHOOK_KEY na Etapa 7, depois de registrar o endpoint do webhook.
3

Implement the Server

Crie src/server.ts. O endpoint de completion chama o modelo gpt-6-luna da OpenAI, adequado para solicitações de alto volume. A aba package.json mostra a lista completa de dependências:
O backend está concluído: checkout de assinatura, checkout de top-up, uma completion da OpenAI com cobrança de tokens baseada em uso, uma leitura de saldo e um handler de webhook verificado.
@dodopayments/ingestion-blueprints fornece trackers que fazem a chamada usageEvents.ingest para você, incluindo o uso de LLM Blueprint, API gateway, object storage, streams e time-range.
4

How Deductions Happen

O servidor nunca chama um endpoint de “deduct N credits”. O meter faz a dedução:
  1. Seu handler chama a OpenAI e lê usage.total_tokens, por exemplo, 1532.
  2. Você ingere um evento de uso com event_name: api.tokens_used e metadata: { tokens: 1532 }.
  3. O Token Usage Meter agrega eventos por cliente. Um worker em segundo plano processa novos eventos a cada minuto.
  4. Como o meter cobra o crédito API Tokens por meio de Bill usage in credits, Dodo Payments deduz 1532 créditos, começando pelo grant do cliente que expira primeiro (FIFO).
  5. Se o overage estiver habilitado e o saldo acabar, o déficit será rastreado e cobrado na próxima invoice.
Seu código apenas ingere eventos.

Etapa 6: Adicione um Frontend de Demonstração

Crie public/index.html para testar todos os fluxos no navegador. A página salva o ID do cliente em localStorage, para que subscribe, generate e top-up compartilhem uma identidade, como fariam em um app com login:

Etapa 7: Configure o Webhook

Webhooks permitem que seu servidor reaja a alterações de saldo, por exemplo, enviando um e-mail a um cliente cujo saldo esteja acabando.
1

Expose Your Local Server

Webhooks precisam de uma URL pública. Para desenvolvimento local, use o ngrok ou outro túnel:
Copie a URL de encaminhamento HTTPS, que termina em ngrok-free.app.
2

Register the Webhook in Dodo Payments

  1. No dashboard, acesse Developer → Webhooks e clique em Add endpoint.
  2. Insira a URL https://your-tunnel.ngrok-free.app/webhooks/dodo, usando o host do seu próprio túnel.
  3. Selecione pelo menos estes eventos:
    • credit.added
    • credit.deducted
    • credit.overage_charged
  4. Clique em Create endpoint e copie o signing secret da aba Overview do endpoint.
  5. Cole-o em .env como DODO_PAYMENTS_WEBHOOK_KEY e reinicie npm run dev.
O dodo.webhooks.unwrap() do SDK verifica os cabeçalhos webhook-id, webhook-timestamp e webhook-signature com seu signing secret e, em seguida, analisa o payload. Não escreva sua própria verificação HMAC: Dodo Payments segue Standard Webhooks, que assina id.timestamp.body, não apenas o body.

Etapa 8: Teste o Fluxo Completo

1

Subscribe a Test Customer

  1. Execute npm run dev.
  2. Abra http://localhost:3000.
  3. Selecione Pro, insira um endereço de e-mail e um nome de teste e clique em Get Checkout Link. Conclua o checkout usando os dados do cartão de teste.
  4. No dashboard, acesse Customers, abra o cliente mais recente e copie o ID, que começa com cus_.
  5. Cole o ID no campo Logged-in customer ID da demonstração e clique em Save.
O cliente tem 40.000.000 de tokens. Clique em Refresh Balance para confirmar.
2

Generate an AI Response

Digite um prompt e clique em Generate. O servidor chama a OpenAI, lê o total_tokens real, ingere um evento de uso e retorna a resposta.
Um worker em segundo plano processa eventos de uso a cada minuto, portanto o saldo não diminui imediatamente. Aguarde um ou dois minutos e clique novamente em Refresh Balance. Um saldo inalterado na primeira atualização não significa que o metering falhou.
3

Test the Top-Up Flow

Clique em Buy 5M Tokens — $19 e conclua o checkout. Após a aprovação do pagamento, atualize o saldo: ele aumenta em 5.000.000 de tokens, e o log do servidor mostra um evento credit.added.

Solução de problemas

Possíveis causas:
  • O nome do evento do meter não corresponde ao event_name enviado por você. api.tokens_used diferencia maiúsculas de minúsculas.
  • O meter não está vinculado ao crédito API Tokens do produto. Abra a configuração do meter do produto e confirme se Bill usage in credits está ativado.
  • A chave metadata.tokens não corresponde à propriedade Over Property do meter.
  • O grant do cliente expirou. Verifique o histórico de créditos do cliente.
O que verificar:
  1. Em Products → Meters, abra o meter e confirme se o anexo do produto mostra o nome do crédito vinculado.
  2. Abra a aba Events do meter. Os eventos ingeridos aparecem ali mesmo antes de qualquer dedução.
  3. Abra o cliente em Customers e selecione a aba Credits. As entradas do ledger aparecem em um ou dois minutos.
Possíveis causas:
  • O cliente não concluiu o checkout. Os créditos são emitidos somente após um pagamento bem-sucedido.
  • Você está consultando com o customer_id incorreto. Use o ID que começa com cus_ no dashboard, não um ID do seu próprio banco de dados.
  • CREDIT_ENTITLEMENT_ID em .env não corresponde ao crédito vinculado ao produto.
O que verificar: Abra o cliente em Customers e selecione a aba Credits. Se nenhum crédito aparecer, o crédito não foi vinculado ao produto ou o pagamento não foi concluído.
Possíveis causas:
  • O overage não está habilitado no credit attachment do produto Pro. A configuração no crédito é apenas um padrão.
  • O cliente está no Starter, não no Pro.
  • Overage Limit está definido como 0.
O que verificar: Edite o produto Pro, abra o crédito em Entitlements e confirme se Allow Overage está ativado e se Price Per Unit é 0.000005 ($5 por milhão de tokens). Verifique os zeros à esquerda: o campo aceita um preço por token, não por 1K tokens.
Possíveis causas:
  • Ordem de análise do body: express.json() foi executado em /webhooks/dodo antes de express.raw(). O SDK precisa dos bytes brutos da solicitação, não de JSON analisado.
  • DODO_PAYMENTS_WEBHOOK_KEY contém o signing secret incorreto.
  • Um proxy reverso reescreve os cabeçalhos da solicitação.
O que verificar: Confirme se a linha app.use('/webhooks/dodo', express.raw(...)) vem antes de app.use(express.json()) em server.ts.

Precisa de ajuda?

Parabéns! Você criou o Billing baseado em créditos para a NeuralAPI

A NeuralAPI agora cobra em créditos, do checkout à dedução:

Token Credit Entitlement

Um crédito API Tokens reutilizável com prazo de expiração de 30 dias, compartilhado por ambos os planos e pelo pacote de top-up.

Tiered Plans, One Credit

Starter (10 milhões de tokens, limite rígido) e Pro (40 milhões de tokens mais overage), configurados por produto sem duplicar o crédito.

One-Time Top-Up Pack

Os clientes adicionam 5 milhões de tokens por $19 sem alterar a assinatura.

Deduction Through a Meter

As contagens reais de tokens da OpenAI são ingeridas como eventos, e o meter deduz créditos em ordem FIFO sem rastreamento manual.

Live Balance API

O saldo atual, lido por meio do SDK, para controlar o acesso, mostrar o uso ou avisar os clientes no seu app.

Verified Webhook Pipeline

Eventos do ledger de créditos (credit.added, credit.deducted, credit.overage_charged) encaminhados por um handler que verifica assinaturas com o helper Standard Webhooks do SDK.
Vai para produção? Reforce estes pontos:
  • Adicione autenticação a /credits/:customerId e /api/generate. Como está escrito, qualquer pessoa pode chamá-los com qualquer ID de cliente. Autentique os usuários e consulte o ID do cliente no servidor.
  • Use valores estáveis de event_id. O exemplo usa Date.now() mais uma string aleatória. Em produção, use o ID da sua solicitação para que as tentativas sejam idempotentes: Dodo Payments ignora um evento cujo event_id já tenha sido ingerido.
  • Armazene o mapeamento entre cliente e usuário. Salve customer_id no seu banco de dados após o primeiro checkout, para que os usuários não precisem colá-lo manualmente.
  • Decida o que acontece quando uma assinatura termina. Os créditos do plano permanecem no ledger do cliente até expirarem, 30 dias após a emissão, e os créditos de top-up permanecem válidos por 365 dias. O /api/generate do tutorial verifica apenas o saldo, não o status da assinatura, portanto um cliente que cancelou ainda pode usar os tokens restantes. Esse é o padrão mais conveniente para o cliente. Para um acesso mais restrito, (a) escute o webhook subscription.cancelled e controle o acesso de /api/generate com base no status da assinatura ou (b), após o cancelamento, debite os créditos não utilizados do plano com a API do ledger. As deduções usam o grant que expira primeiro, portanto os créditos do plano de 30 dias são usados antes dos créditos de top-up de 365 dias.
  • Monitore o dashboard de Usage Billing para detectar anomalias de metering rapidamente.

Credit-Based Billing Reference

Rollover, modos de overage, gerenciamento do ledger e todos os endpoints da API de créditos.

Credit Webhook Events

Schemas de payload para todos os eventos de crédito que seu servidor pode receber.
Última modificação em 26 de setembro de 2026