Go 보일러플레이트

GitHub Repository

최소한의 Go + Dodo Payments 보일러플레이트

개요

Go boilerplate는 pricing page에서 Dodo Payments 제품을 판매하는 최소한의 Go 서버입니다. checkout session을 생성하고, 웹훅을 검증 및 처리하며, Customer Portal을 엽니다. 자체 Go backend의 시작점으로 복제하세요.

boilerplate에는 go.mod에 설정된 버전인 Go 1.24.4 이상이 필요합니다. cmd, internal, templates 레이아웃을 사용하고, Go HTML templates로 pricing page를 렌더링하며, dodopayments-go SDK를 통해 Dodo Payments API를 호출합니다.

기능

빠른 설정: repository를 복제하고, .env에 API keys를 추가한 다음 make run로 서버를 시작합니다.
결제 통합: dodopayments-go SDK로 checkout session을 생성하는 checkout flow입니다.
Modern UI: Go HTML templates와 Tailwind CSS로 구축된 dark-themed pricing page입니다.
Webhook 처리: 이벤트를 처리하기 전에 각 웹훅의 signature를 검증합니다.
Customer Portal: Customer Portal을 통한 셀프 서비스 subscription 관리입니다.
Go 모범 사례: cmd, internal, templates를 사용하는 깔끔한 project layout입니다.
Pre-filled Checkout: 고객의 이름과 이메일을 checkout에 전달하므로 고객이 다시 입력할 필요가 없습니다.

전제 조건

시작하기 전에 다음이 필요합니다:

Go 1.24.4 이상. go version로 버전을 확인합니다.
Dodo Payments account. dashboard에서 API key와 webhook signing key를 생성해야 합니다.
최소 하나의 product. dashboard의 Products에서 생성합니다.

빠른 시작

Clone the Repository

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

Install Dependencies

make install

make install는 go mod download를 실행한 다음 go mod tidy를 실행합니다. make 없이 modules를 다운로드하려면 다음을 실행합니다:

go mod download

Get API Credentials

Dodo Payments에 가입한 다음 dashboard에서 두 key를 모두 복사합니다:

API Key: Developer → API Keys
Webhook Key: Developer → Webhooks. 각 webhook endpoint에는 고유한 signing key가 있습니다. 로컬 서버에 연결되는 endpoint를 생성하려면 Testing Webhooks Locally를 참조하세요.

개발하는 동안 두 key를 모두 test mode에서 생성합니다. test mode로 전환하려면 dashboard sidebar에서 Live Mode switch를 끕니다.

Configure Environment Variables

template에서 project root에 .env 파일을 생성합니다:

cp .env.example .env

.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

서버는 시작 시 다음 variables를 읽습니다:

Variable	Required	Default	Purpose
`DODO_PAYMENTS_API_KEY`	Yes	None	Dodo Payments API에 대한 요청을 인증합니다.
`DODO_PAYMENTS_WEBHOOK_KEY`	Yes	None	수신 웹훅의 signature를 검증합니다.
`DODO_PAYMENTS_RETURN_URL`	No	`http://localhost:8080`	결제 후 checkout이 고객을 보내는 URL입니다.
`DODO_PAYMENTS_ENVIRONMENT`	No	`test_mode`	`test_mode` 또는 `live_mode`입니다.
`PORT`	No	`8000`	서버가 수신 대기하는 port입니다.

필수 key 중 하나라도 없으면 서버는 시작 시 종료됩니다. .env.example는 PORT와 DODO_PAYMENTS_RETURN_URL를 port 8080로 설정합니다. 이 page는 port 8000를 사용하므로, 표시된 대로 둘 다 8000로 설정하거나 이 page의 commands에서 8000를 8080로 바꿉니다.

.env 파일을 version control에 절대 commit하지 마세요. repository의 .gitignore는 이미 이 파일을 제외합니다.

Add Your Products

internal/lib/products.go의 sample product를 자신의 products로 바꿉니다. dashboard의 Products에서 각 product ID를 복사합니다:

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는 pricing page에 표시되는 price만 smallest currency unit으로 설정합니다. 9999는 $99.99로 표시됩니다. Checkout은 Dodo Payments에서 product의 price를 청구합니다.

Run the Development Server

make run

make run는 서버를 bin/server로 build한 후 시작합니다. 먼저 binary를 build하지 않고 서버를 실행하려면 다음을 실행합니다:

go run cmd/server/main.go

http://localhost:8000을 열어 pricing page를 확인합니다.

제품이 나열되고 구매할 수 있는 dark-themed pricing page가 표시됩니다.

Project Structure

repository의 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

API Endpoints

boilerplate에는 다음과 같이 미리 구성된 endpoints가 포함되어 있습니다:

Endpoint	Method	Description
`/`	GET	`internal/lib/products.go`의 products를 나열하는 pricing page입니다.
`/api/checkout`	POST	checkout session을 생성합니다. `product_id`와 선택적인 `quantity`(기본값 `1`) 및 `customer`(`email`, `name`, `phone`)를 전송합니다. `session_id`와 `checkout_url`를 반환합니다.
`/api/webhook`	POST	Dodo Payments 웹훅을 검증하고 처리합니다. signature check가 실패하면 `401`를 반환합니다.
`/api/customer-portal`	POST	`portal_url`의 Customer Portal link를 반환합니다. `customer_id` 또는 선택적인 `name`와 함께 `email`를 전송합니다. email만 제공하면 handler가 customer를 조회하고, 없으면 생성합니다.
`/health`	GET	Health check입니다. `OK`를 반환합니다.

Customization

Product Information 업데이트

internal/lib/products.go를 편집하여 다음을 변경합니다:

Product IDs(Dodo Payments dashboard의 Products에서 가져옴)
Names
pricing page에 표시되는 Pricing
Features
Descriptions

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",
        },
    },
}

pricing page template은 모든 price에 /mo suffix를 추가하며, Price가 100000 이상이면 price 대신 Custom을 표시합니다. 이를 변경하려면 templates/index.html를 편집합니다.

Customer Data 미리 입력

.env에서 handleCheckout function은 hardcoded customer data를 /api/checkout로 전송합니다. 이를 로그인한 사용자의 data로 바꿉니다:

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
};

handlePortal function은 이 customer data를 재사용하고, 동일한 sample name과 email로 fallback합니다. production app에서는 두 function 모두 authentication system에서 이 values를 주입합니다.

Webhook Events

internal/api/webhook.go는 client.Webhooks.Unwrap와 DODO_PAYMENTS_WEBHOOK_KEY의 key를 사용해 각 request를 검증한 다음, type에 따라 event를 route합니다. 다음 event에는 handler가 있으며, 각 handler가 event data를 log합니다:

Event	Description
`payment.succeeded`	payment가 successful일 때 trigger됨
`payment.failed`	payment attempt가 실패할 때 trigger됨
`subscription.active`	subscription이 active 상태가 될 때 trigger됨
`subscription.renewed`	subscription이 다음 billing period로 renew될 때 trigger됨
`subscription.updated`	subscription field가 변경될 때마다 trigger됨
`subscription.cancelled`	subscription이 cancelled될 때 trigger됨

handler는 subscription.on_hold, subscription.failed, subscription.expired, subscription.plan_changed도 아무 action 없이 허용하며, 그 밖의 모든 event type은 unhandled로 log합니다. 검증된 모든 event에 200로 응답합니다. 모든 event type은 Webhook Event Guide를 참조하세요. handler functions에 다음을 수행하는 business logic을 추가합니다:

database의 user permissions 업데이트
confirmation email 전송
digital products에 대한 access provisioning
analytics와 metrics 추적

Testing Webhooks Locally

Dodo Payments는 localhost에 연결할 수 없습니다. 개발 중 웹훅을 수신하려면 ngrok과 같은 tunnel을 사용해 local server를 외부에 노출합니다:

ngrok http 8000

Dodo Payments Dashboard에서 ngrok이 출력하는 forwarding URL 뒤에 /api/webhook를 붙인 URL로 endpoint를 추가합니다:

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

endpoint의 signing key를 DODO_PAYMENTS_WEBHOOK_KEY에 복사한 다음 서버를 재시작합니다.

Deployment

Production용 Build

make build는 서버를 bin/server로 compile합니다:

make build

make 없이 binary를 build하고 시작하려면 다음을 실행합니다:

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

Vercel에 Deploy

[

](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate) deploy 후 .env 파일의 variables를 Vercel project settings에 추가합니다. .env는 repository에 포함되지 않기 때문입니다. 그런 다음 dashboard에서 webhook endpoint를 https://yourdomain.com/api/webhook로 설정합니다.

Docker

project root에 Dockerfile를 생성합니다. build stage는 go.mod와 일치하도록 Go 1.24.4 이상을 사용해야 합니다:

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"]

server가 working directory에서 templates를 로드하므로 final image는 templates/를 binary 옆에 복사합니다. image를 build하고 실행합니다:

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

container는 .env의 PORT 값을 수신 대기하므로, port mapping과 일치하도록 PORT=8000를 유지합니다.

Production 고려 사항

production에 deploy하기 전에:

DODO_PAYMENTS_ENVIRONMENT를 live_mode로 설정합니다.
dashboard의 live mode API key를 사용합니다.
webhook endpoint를 production domain으로 지정하고 해당 endpoint의 signing key를 사용합니다.
DODO_PAYMENTS_RETURN_URL를 production domain의 page로 설정합니다.
모든 endpoint를 HTTPS로 제공합니다.

Troubleshooting

Build errors or missing dependencies

go version가 Go 1.24.4 이상을 보고하는지 확인한 다음 modules를 다시 다운로드합니다:

go mod tidy
go mod download

Checkout session creation fails

일반적인 원인:

product ID가 유효하지 않습니다. API key와 동일한 mode의 Products에 존재하는지 확인합니다.
.env의 API key 또는 DODO_PAYMENTS_ENVIRONMENT가 잘못되었습니다. test mode key에는 test_mode가 필요합니다.
정확한 error는 server logs를 확인합니다. handler는 500를 반환하기 전에 실패한 모든 request를 log합니다.

Webhooks not receiving events

local testing을 위해 ngrok으로 server를 노출합니다:

ngrok http 8000

Dodo Payments dashboard에서 webhook URL을 ngrok URL로 설정합니다. 그런 다음 .env의 DODO_PAYMENTS_WEBHOOK_KEY를 해당 endpoint의 signing key로 설정합니다. server logs에 webhook verification failed가 기록되면 key가 endpoint와 일치하지 않는 것입니다.

Templates not loading

server는 working directory에서 templates/base.html와 templates/index.html를 로드합니다. project root에서 server를 시작하거나 cmd/server/main.go의 template paths를 변경합니다.

Learn More

Go SDK

Complete Go SDK documentation

Webhooks Documentation

모든 webhook events와 모범 사례 알아보기

Checkout Sessions

checkout session configuration 자세히 알아보기

API Reference

Complete Dodo Payments API documentation

Support

boilerplate에 대한 도움이 필요하면 다음을 수행하세요:

Discord community에서 질문합니다.
문제와 업데이트는 GitHub repository를 확인합니다.
support team에 문의합니다.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

GitHub Repository

개요

기능

전제 조건

빠른 시작

Project Structure

API Endpoints

Customization

Product Information 업데이트

Customer Data 미리 입력

Webhook Events

Testing Webhooks Locally

Deployment

Production용 Build

Vercel에 Deploy

Docker

Production 고려 사항

Troubleshooting

Learn More

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

Support

GitHub Repository

​개요

​기능

​전제 조건

​빠른 시작

​Project Structure

​API Endpoints

​Customization

​Product Information 업데이트

​Customer Data 미리 입력

​Webhook Events

​Testing Webhooks Locally

​Deployment

​Production용 Build

​Vercel에 Deploy

​Docker

​Production 고려 사항

​Troubleshooting

​Learn More

Go SDK

Webhooks Documentation

Checkout Sessions

API Reference

​Support

개요

기능

전제 조건

빠른 시작

Project Structure

API Endpoints

Customization

Product Information 업데이트

Customer Data 미리 입력

Webhook Events

Testing Webhooks Locally

Deployment

Production용 Build

Vercel에 Deploy

Docker

Production 고려 사항

Troubleshooting

Learn More

Support