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á o MailKit, um serviço de email transacional no qual os clientes pré-pagam por créditos de email. Um plano mensal concede 5.000 emails por ciclo de cobrança. Quando os créditos de um cliente ficam baixos, ele compra um pacote de recarga em vez de esperar o próximo ciclo. Cada envio debita um crédito.
Este tutorial usa o Resend como provedor de email. O plano gratuito (3.000 emails por mês) é suficiente para criar e testar todo o fluxo. O padrão de cobrança funciona com qualquer provedor: substitua resend.emails.send por uma chamada ao SendGrid, Postmark, Amazon SES ou ao seu próprio relay SMTP.
Ao terminar, você saberá como:
  • Criar um entitlement de crédito personalizado para emails no dashboard.
  • Associar créditos a um plano de assinatura e a um produto de recarga avulsa.
  • Enviar emails pelo Resend e debitar um crédito por envio com uma entrada no ledger.
  • Ler o saldo de créditos atualizado de um cliente no frontend.
  • Verificar webhooks do Dodo Payments e tratar credit.balance_low para avisar os clientes antes que o saldo chegue a zero.

O que vamos criar

O MailKit vende dois produtos: A unidade é um email = um crédito. Os clientes não precisam entender tokens, lotes ou unidades ponderadas. Eles veem “4.231 emails restantes este mês.” Antes de começar, você precisa de:
  • Uma conta do Dodo Payments. Faça tudo no modo de teste.
  • Uma conta gratuita do Resend e uma API key.
  • Node.js 22 ou posterior e conhecimento prático de TypeScript.

Etapa 1: Crie seu entitlement de crédito para emails

O entitlement de crédito define a unidade vendida pelo MailKit: um envio de email.
Aba Credits em Products, listando os entitlements de crédito da empresa

The Credits tab under Products lists all your credit entitlements.

1

Open the Credits Section

  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: Email CreditsCredit Type: Custom UnitUnit Name: emailDefine Precision: 0. Um email é uma unidade inteira, portanto o saldo nunca precisa de casas decimais.Credit Expiry: 30 days. Os créditos não utilizados expiram 30 dias após serem emitidos.
A precisão não pode ser alterada depois que você cria o crédito. Para unidades discretas, como emails, mensagens ou sessões, use 0.
3

Leave the Other Defaults

Este tutorial mantém rollover e overage desativados para simplificar o fluxo de créditos. Você pode ativá-los depois, no crédito ou no vínculo de crédito de cada produto.
4

Save and Copy the Credit ID

Clique em Create Credit. Abra o crédito e copie seu ID, que começa com cde_. O backend o utiliza para consultar saldos e criar entradas no ledger.
O entitlement Email Credits está pronto. Agora, crie os produtos que o concedem aos clientes.

Etapa 2: Crie o plano e o pacote de recarga

Crie dois produtos que associem o mesmo entitlement Email Credits: um plano de Subscription que concede 5.000 emails a cada ciclo de cobrança e uma recarga One Time que adiciona mais 5.000 sob demanda.
Este tutorial debita créditos com entradas no ledger em vez de medidores de uso. Um débito no ledger é aplicado quando a chamada da API retorna, não exige configuração de medidor e atende a casos em que cada ação do usuário custa exatamente um crédito. Para deduzir créditos automaticamente de eventos de uso ingeridos, o que é adequado para unidades ponderadas, como tokens ou megabytes processados, consulte Usage Billing with Credits no guia Credit-Based Billing.

Plano MailKit ($19/mês, 5.000 emails)

1

Create the Subscription

  1. Acesse Products e clique em Add Product.
  2. Insira os detalhes do produto:
Product Name: MailKit PlanDescription: 5,000 transactional emails per month.
  1. Em Pricing Type, selecione Subscription.
  2. Defina o preço recorrente:
Price: 19.00Repeat payment every: 1 mêsCurrency: USD
2

Attach the Email Credit Entitlement

Na seção Entitlements, clique em Attach ao lado de Credits e configure:Select credits: Email CreditsCredits issued per billing cycle: 5000Low Balance Threshold (%): 20. O Dodo Payments envia credit.balance_low quando o saldo fica abaixo de 20% dos créditos emitidos por ciclo, ou seja, 1.000 emails.Import Default Credit Settings: ativado, para que o produto use a expiração de 30 dias da Etapa 1.Adicione o crédito ao produto e salve-o. Copie o ID do produto, que começa com pdt_.
Plano: $19/mês, com 5.000 emails emitidos a cada ciclo de cobrança.

Pacote de Recarga ($9 avulso, 5.000 emails)

1

Create a One-Time Product

  1. Acesse Products e clique em Add Product.
  2. Insira os detalhes do produto:
Product Name: Email Top-Up PackDescription: Add 5,000 emails to your MailKit balance.
  1. Em Pricing Type, selecione One Time.
  2. Defina o preço:
Price: 9.00Currency: USD
2

Attach the Credit Grant

Na seção Entitlements, clique em Attach ao lado de Credits e configure:
  • Select credits: Email Credits
  • No of credits issued: 5000
Um produto avulso concede créditos com sua própria expiração: 30 dias a partir da compra, conforme o padrão definido na Etapa 1. Os créditos de recarga são adicionados aos créditos da assinatura. Eles não os substituem.
Salve o produto e copie seu ID.
Pacote de Recarga: $9 por 5.000 emails, adicionados ao saldo após a aprovação do pagamento.

Etapa 3: Configure o backend

Crie o servidor Express que cria checkouts, envia emails, lê saldos e recebe webhooks.
1

Initialize the Project

Adicione um script de desenvolvimento a package.json:
tsx executa TypeScript diretamente, sem uma etapa de build ou um tsconfig.json. Em produção, adicione um tsconfig.json e um script build.
2

Configure Environment Variables

Crie .env com uma API key do modo de teste em Developer → API Keys e os IDs das Etapas 1 e 2:
.env
Você preencherá DODO_PAYMENTS_WEBHOOK_KEY na Etapa 4, depois de criar o endpoint do webhook. Crie a API key do Resend em resend.com/api-keys.
Adicione .env a .gitignore antes do primeiro commit. Nunca faça commit de API keys.
3

Build the Server

Crie server.ts na raiz do projeto. O servidor expõe cinco rotas: checkout de assinatura, checkout de recarga, leitura de saldo, envio e recebimento de webhook.
A rota do webhook precisa receber o corpo bruto da requisição. express.json() substitui o corpo por um objeto analisado, e a verificação da assinatura precisa dos bytes exatos assinados pelo Dodo Payments. Mantenha a rota /webhooks/dodo, com express.raw(), acima da linha app.use(express.json()).
O backend está pronto: assinatura, recarga, saldo, envio e o handler do webhook.
4

Add a Demo UI

Crie public/index.html. Ele chama cada rota a partir de um formulário simples, para que você possa testar o fluxo no navegador:

Etapa 4: Configure o endpoint do webhook

O evento credit.balance_low permite avisar os clientes antes que fiquem sem créditos. Sem ele, o cliente só percebe o problema quando um email não consegue ser enviado.
1

Expose Your Local Server

Webhooks precisam de uma URL pública. Durante o desenvolvimento, use ngrok ou outro túnel:
Copie a URL de encaminhamento HTTPS, por exemplo https://1234abcd.ngrok-free.app.
2

Register the Endpoint in Dodo Payments

  1. Acesse Developer → Webhooks e clique em Add endpoint.
  2. Insira a URL https://1234abcd.ngrok-free.app/webhooks/dodo, usando o host do seu túnel.
  3. Selecione os eventos credit.added, credit.balance_low e credit.rolled_over.
  4. Clique em Create endpoint.
  5. Copie o signing secret da aba Overview do endpoint para .env como DODO_PAYMENTS_WEBHOOK_KEY.
  6. Reinicie o servidor.

Etapa 5: Teste o fluxo completo

1

Start the Server

O servidor registra MailKit running on http://localhost:3000. Abra essa URL no navegador.
2

Subscribe a Test Customer

  1. Na seção 1, insira um endereço de email e um nome de teste e clique em Get checkout link.
  2. Abra o link e conclua o checkout com um cartão de teste.
  3. No dashboard, acesse Customers e copie o ID do novo cliente, que começa com cus_.
O cliente tem 5.000 emails no saldo. Para confirmar, abra o cliente em Customers e selecione a aba Credits.
3

Send an Email

  1. Cole o ID do cliente na seção 3.
  2. Deixe To definido como delivered@resend.dev, um endereço de teste do Resend que aceita todas as mensagens.
  3. Clique em Send.
A página exibe o ID da mensagem do Resend. Atualize o saldo na seção 2: ele mostra 4.999. Um débito no ledger faz parte do saldo assim que a chamada da API retorna.
4

Trigger the Low-Balance Webhook

O limite é 20%, ou 1.000 dos 5.000 emails emitidos por ciclo. Para alcançá-lo sem enviar 4.000 emails, debite o saldo manualmente no dashboard:
  1. Abra o cliente em Customers, selecione a aba Credits e escolha Email Credits.
  2. Clique em Apply Credit/Debit, selecione Debit e insira 4000. O saldo agora é exatamente 1.000, portanto ainda não está abaixo do limite.
  3. Envie mais um email pela demonstração. O saldo cai para 999.
Quando o webhook chegar, o servidor registra:
O servidor recebeu e verificou o webhook. Em produção, é aqui que você envia um email ao cliente ou exibe um banner no aplicativo.
5

Buy a Top-Up Pack

  1. Cole o ID do cliente na seção 4.
  2. Clique em Buy 5,000 emails e conclua o checkout de teste.
  3. Atualize o saldo. Ele aumenta em 5.000.
O Dodo Payments envia um evento credit.added com transaction_type: "credit_added". O grant associado tem source_type: one_time, que você pode consultar pela API List Customer Grants. Os créditos de recarga são adicionados aos créditos da assinatura. Os débitos usam primeiro o grant que expira antes e, quando dois expiram ao mesmo tempo, o grant mais antigo.
6

Test the Hard Stop

Debite o saldo até zero no dashboard e tente enviar mais um email. O servidor responde com 402:
Esse 402 é a regra de controle da sua aplicação. Trate a API de saldo do Dodo Payments como fonte da verdade e não armazene o saldo em cache no cliente.

Solução de problemas

A assinatura abrange o corpo bruto do HTTP. express.json() substitui o corpo por um objeto analisado, portanto a verificação falha. Registre /webhooks/dodo com express.raw({ type: 'application/json' }) acima da linha app.use(express.json()). Depois, verifique se DODO_PAYMENTS_WEBHOOK_KEY corresponde ao signing secret na aba Overview do endpoint.
Verifique estas três coisas, nesta ordem:
  1. O cliente concluiu o checkout. Os créditos são emitidos quando o pagamento é aprovado, não quando a sessão de checkout é criada.
  2. CREDIT_ENTITLEMENT_ID em .env corresponde ao crédito associado ao produto. As chamadas de saldo e ledger usam esse ID, portanto uma divergência lê ou debita um crédito diferente.
  3. O customer_id informado é o ID do cliente no Dodo Payments (começa com cus_), não um ID do seu próprio banco de dados.
O remetente de teste onboarding@resend.dev entrega somente ao endereço de email da sua conta do Resend ou a delivered@resend.dev. Para enviar a qualquer outra pessoa, verifique um domínio e use um endereço from nesse domínio.

O que você criou

One Reusable Credit Unit

Email Credits, definido uma vez e associado ao plano de assinatura e ao pacote de recarga.

Subscription with Prepaid Allowance

$19/mês concede 5.000 emails por ciclo de cobrança. Os clientes sabem pelo que estão pagando, e você conhece seu custo máximo.

Top-Up Pack

Um produto avulso que concede 5.000 emails além dos créditos da assinatura, sem alterar o plano.

Direct Ledger Debits

Uma chamada createLedgerEntry após cada envio, sem medidor e sem atraso de agregação. O ID da mensagem do Resend como chave de idempotência impede um segundo débito para o mesmo envio.

Credit-Based Billing Reference

Rollover, modos de overage, gerenciamento do ledger e a API completa de créditos.
Para obter ajuda, pergunte na Discord Community ou envie um email para support@dodopayments.com.
Última modificação em 26 de setembro de 2026