Go Boilerplate

GitHub Repository

Boilerplate mínimo Go + Dodo Payments

Visão Geral

O boilerplate Go é um servidor Go minimalista que vende seus produtos do Dodo Payments a partir de uma página de preços. Ele cria sessões de checkout, verifica e processa webhooks e abre o Customer Portal. Clone-o como ponto de partida para seu próprio backend Go.

O boilerplate requer Go 1.24.4 ou posterior, a versão definida em seu go.mod. Ele usa um layout cmd, internal e templates, renderiza a página de preços com templates HTML do Go e chama a API do Dodo Payments por meio do SDK dodopayments-go.

Recursos

Configuração rápida: clone o repositório, adicione suas chaves de API a .env e inicie o servidor com make run.
Integração de pagamentos: um fluxo de checkout que cria sessões de checkout com o SDK dodopayments-go.
UI moderna: uma página de preços com tema escuro, criada com templates HTML do Go e Tailwind CSS.
Processamento de webhooks: verifica a assinatura de cada webhook antes de processar o evento.
Customer Portal: gerenciamento de assinaturas self-service por meio do Customer Portal.
Boas práticas de Go: um layout de projeto organizado com cmd, internal e templates.
Checkout pré-preenchido: envia o nome e o email do cliente para o checkout, para que ele não precise digitá-los novamente.

Pré-requisitos

Antes de começar, você precisa de:

Go 1.24.4 ou posterior. Verifique sua versão com go version.
Uma conta do Dodo Payments, para criar uma chave de API e uma chave de assinatura de webhook no dashboard.
Pelo menos um produto, criado em Products no dashboard.

Início Rápido

Clone the Repository

git clone https://github.com/dodopayments/go-boilerplate.git
cd go-boilerplate

Install Dependencies

make install

make install executa go mod download e depois go mod tidy. Para baixar os módulos sem make, execute:

go mod download

Get API Credentials

Cadastre-se no Dodo Payments e copie as duas chaves do dashboard:

Chave de API: Developer → API Keys
Chave de webhook: Developer → Webhooks. Cada endpoint de webhook tem sua própria chave de assinatura. Para criar um endpoint que alcance seu servidor local, consulte Testando Webhooks Localmente.

Crie as duas chaves no modo de teste enquanto desenvolve. Para mudar para o modo de teste, desative a opção Live Mode na barra lateral do dashboard.

Configure Environment Variables

Crie um arquivo .env na raiz do projeto usando o template:

cp .env.example .env

Defina estes valores em .env:

.env

DODO_PAYMENTS_API_KEY=your_api_key_here
DODO_PAYMENTS_WEBHOOK_KEY=your_webhook_signing_key_here
DODO_PAYMENTS_RETURN_URL=http://localhost:8000
DODO_PAYMENTS_ENVIRONMENT=test_mode
PORT=8000

O servidor lê estas variáveis na inicialização:

Variável	Obrigatória	Padrão	Finalidade
`DODO_PAYMENTS_API_KEY`	Sim	Nenhum	Autentica solicitações à API do Dodo Payments.
`DODO_PAYMENTS_WEBHOOK_KEY`	Sim	Nenhum	Verifica a assinatura de webhooks recebidos.
`DODO_PAYMENTS_RETURN_URL`	Não	`http://localhost:8080`	A URL para a qual o checkout envia o cliente após o pagamento.
`DODO_PAYMENTS_ENVIRONMENT`	Não	`test_mode`	`test_mode` ou `live_mode`.
`PORT`	Não	`8000`	A porta em que o servidor escuta.

O servidor é encerrado na inicialização se alguma das chaves obrigatórias estiver ausente. .env.example define PORT e DODO_PAYMENTS_RETURN_URL como a porta 8080. Esta página usa a porta 8000, portanto defina ambas como 8000, conforme mostrado, ou substitua 8000 por 8080 nos comandos desta página.

Nunca faça commit do arquivo .env no controle de versão. O .gitignore do repositório já o exclui.

Add Your Products

Substitua o produto de exemplo em internal/lib/products.go pelos seus produtos. Copie o ID de cada produto em Products no dashboard:

var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999, // in cents
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
    // ... add more products
}

Price define apenas o preço exibido pela página de preços, na menor unidade da moeda: 9999 é exibido como $99.99. O checkout cobra o preço do produto no Dodo Payments.

Run the Development Server

make run

make run compila o servidor em bin/server e o inicia. Para executar o servidor sem compilar um binário primeiro, execute:

go run cmd/server/main.go

Abra http://localhost:8000 para ver sua página de preços.

Você verá uma página de preços com tema escuro que lista seus produtos, pronta para compras.

Estrutura do projeto

O repositório tem este layout:

go-boilerplate/
├── cmd/
│   └── server/             # Application entry point (main.go)
├── internal/
│   ├── api/                # API handlers: checkout.go, portal.go, webhook.go
│   ├── core/               # Configuration loading (config.go)
│   └── lib/                # Shared logic: products.go, customers.go
├── templates/              # HTML templates: base.html, index.html
├── Makefile                # Build and run commands
├── go.mod                  # Go module definition
├── go.sum                  # Dependency checksums
├── .env.example            # Environment template
└── README.md

Endpoints da API

O boilerplate inclui os seguintes endpoints pré-configurados:

Endpoint	Método	Descrição
`/`	GET	Página de preços que lista os produtos em `internal/lib/products.go`.
`/api/checkout`	POST	Cria uma sessão de checkout. Envie `product_id`, além de `quantity` opcional (padrão `1`) e `customer` (`email`, `name`, `phone`). Retorna `session_id` e `checkout_url`.
`/api/webhook`	POST	Verifica e processa webhooks do Dodo Payments. Retorna `401` quando a verificação da assinatura falha.
`/api/customer-portal`	POST	Retorna um link do Customer Portal em `portal_url`. Envie `customer_id` ou `email` com um `name` opcional. Se apenas um email for informado, o handler procura o cliente e cria um caso ele não exista.
`/health`	GET	Verificação de integridade. Retorna `OK`.

Personalização

Atualizar informações do produto

Edite internal/lib/products.go para alterar:

IDs dos produtos (em Products no dashboard do Dodo Payments)
Nomes
Preços exibidos na página de preços
Recursos
Descrições

var Products = []Product{
    {
        ProductID:   "pdt_001", // Replace with your product ID
        Name:        "Basic Plan",
        Description: "Get access to basic features and support",
        Price:       9999,
        Features: []string{
            "Access to basic features",
            "Email support",
            "1 Team member",
            "Basic analytics",
        },
    },
}

O template da página de preços adiciona um sufixo /mo a cada preço e exibe Custom em vez de um preço quando Price é igual ou maior que 100000. Para alterar isso, edite templates/index.html.

Pré-preencher dados do cliente

Em .env, a função handleCheckout envia dados de cliente definidos no código para /api/checkout. Substitua-os pelos dados do usuário conectado:

const customerData = {
    name: "John Doe",       // Replace with actual logged-in user's name
    email: "john@example.com"  // Replace with actual logged-in user's email
};

A função handlePortal reutiliza esses dados do cliente e usa como alternativa o mesmo nome e email de exemplo. Em um app de produção, injete esses valores do seu sistema de autenticação em ambas as funções.

Eventos de webhook

internal/api/webhook.go verifica cada solicitação com client.Webhooks.Unwrap e a chave em DODO_PAYMENTS_WEBHOOK_KEY e depois encaminha o evento de acordo com seu type. Esses eventos têm um handler, e cada handler registra os dados do evento:

Evento	Descrição
`payment.succeeded`	Acionado quando um pagamento é bem-sucedido
`payment.failed`	Acionado quando uma tentativa de pagamento falha
`subscription.active`	Acionado quando uma assinatura se torna ativa
`subscription.renewed`	Acionado quando uma assinatura é renovada para o próximo período de cobrança
`subscription.updated`	Acionado quando qualquer campo da assinatura é alterado
`subscription.cancelled`	Acionado quando uma assinatura é cancelada

O handler também aceita subscription.on_hold, subscription.failed, subscription.expired e subscription.plan_changed sem executar nenhuma ação e registra todos os outros tipos de evento como não processados. Ele responde com 200 a todos os eventos verificados. Para conhecer todos os tipos de evento, consulte o Guia de eventos de webhook. Adicione sua lógica de negócio às funções do handler para:

Atualizar permissões de usuários no banco de dados
Enviar emails de confirmação
Provisionar acesso a produtos digitais
Acompanhar análises e métricas

Testando webhooks localmente

O Dodo Payments não consegue alcançar localhost. Para receber webhooks durante o desenvolvimento, exponha seu servidor local com um tunnel, como o ngrok:

ngrok http 8000

No Dodo Payments Dashboard, adicione um endpoint com a URL de encaminhamento exibida pelo ngrok, seguida de /api/webhook:

https://your-ngrok-url.ngrok.io/api/webhook

Copie a chave de assinatura do endpoint para DODO_PAYMENTS_WEBHOOK_KEY e reinicie o servidor.

Implantação

Compilar para produção

make build compila o servidor em bin/server:

make build

Para compilar e iniciar o binário sem make, execute:

go build -o bin/server cmd/server/main.go
./bin/server

Implantar na Vercel

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate) Após a implantação, adicione as variáveis do arquivo .env às configurações do projeto na Vercel, pois .env não está no repositório. Em seguida, defina o endpoint de webhook no dashboard como https://yourdomain.com/api/webhook.

Docker

Crie um Dockerfile na raiz do projeto. O estágio de compilação deve usar Go 1.24.4 ou posterior para corresponder a go.mod:

FROM golang:1.24-alpine AS builder

WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN go build -o bin/server cmd/server/main.go

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app/bin/server .
COPY --from=builder /app/templates ./templates

EXPOSE 8000
CMD ["./server"]

A imagem final copia templates/ para o mesmo diretório do binário, pois o servidor carrega os templates a partir do diretório de trabalho. Compile e execute a imagem:

docker build -t go-dodo .
docker run -p 8000:8000 --env-file .env go-dodo

O container escuta no valor de PORT definido em .env, portanto mantenha PORT=8000 para corresponder ao mapeamento de portas.

Considerações para produção

Antes de implantar em produção:

Defina DODO_PAYMENTS_ENVIRONMENT como live_mode.
Use uma chave de API do modo live obtida no dashboard.
Aponte o endpoint de webhook para seu domínio de produção e use a chave de assinatura desse endpoint.
Defina DODO_PAYMENTS_RETURN_URL como uma página no seu domínio de produção.
Disponibilize todos os endpoints por HTTPS.

Solução de problemas

Build errors or missing dependencies

Verifique se go version informa Go 1.24.4 ou posterior e baixe os módulos novamente:

go mod tidy
go mod download

Checkout session creation fails

Causas comuns:

O ID do produto é inválido. Verifique se ele existe em Products no mesmo modo da sua chave de API.
A chave de API ou DODO_PAYMENTS_ENVIRONMENT em .env está incorreta. Uma chave do modo de teste precisa de test_mode.
Para ver o erro exato, consulte os logs do servidor. O handler registra cada solicitação com falha antes de retornar 500.

Webhooks not receiving events

Para testes locais, exponha seu servidor com o ngrok:

ngrok http 8000

Defina a URL do webhook no seu dashboard do Dodo Payments como a URL do ngrok. Em seguida, defina DODO_PAYMENTS_WEBHOOK_KEY em .env como a chave de assinatura desse endpoint. Se o servidor registrar webhook verification failed, a chave não corresponde ao endpoint.

Templates not loading

O servidor carrega templates/base.html e templates/index.html a partir do diretório de trabalho. Inicie o servidor na raiz do projeto ou altere os caminhos dos templates em cmd/server/main.go.

Saiba mais

Go SDK

Documentação completa do SDK Go

Webhooks Documentation

Saiba mais sobre todos os eventos de webhook e as boas práticas

Checkout Sessions

Aprofunde-se na configuração de sessões de checkout

API Reference

Documentação completa da API do Dodo Payments

Suporte

Para obter ajuda com o boilerplate:

Faça perguntas na comunidade do Discord.
Consulte o repositório no GitHub para ver problemas e atualizações.
Entre em contato com a equipe de suporte.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

Visão Geral

Recursos

Pré-requisitos

Início Rápido

Estrutura do projeto

Endpoints da API

Personalização

Atualizar informações do produto

Pré-preencher dados do cliente

Eventos de webhook

Testando webhooks localmente

Implantação

Compilar para produção

Implantar na Vercel

Docker

Considerações para produção

Solução de problemas

Saiba mais

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

Suporte

GitHub Repository

​Visão Geral

​Recursos

​Pré-requisitos

​Início Rápido

​Estrutura do projeto

​Endpoints da API

​Personalização

​Atualizar informações do produto

​Pré-preencher dados do cliente

​Eventos de webhook

​Testando webhooks localmente

​Implantação

​Compilar para produção

​Implantar na Vercel

​Docker

​Considerações para produção

​Solução de problemas

​Saiba mais

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Suporte

Visão Geral

Recursos

Pré-requisitos

Início Rápido

Estrutura do projeto

Endpoints da API

Personalização

Atualizar informações do produto

Pré-preencher dados do cliente

Eventos de webhook

Testando webhooks localmente

Implantação

Compilar para produção

Implantar na Vercel

Docker

Considerações para produção

Solução de problemas

Saiba mais

Suporte