> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Go Boilerplate

> Bắt đầu nhanh chóng với boilerplate Go tối thiểu của chúng tôi để tích hợp Dodo Payments vào các ứng dụng backend Go của bạn

<Card title="GitHub Repository" icon="github" href="https://github.com/dodopayments/go-boilerplate">
  Boilerplate Go + Dodo Payments tối giản
</Card>

## Tổng quan

Boilerplate Go cung cấp một điểm khởi đầu sẵn sàng cho sản xuất để tích hợp Dodo Payments với backend Go của bạn. Mẫu này bao gồm xử lý phiên thanh toán, xác minh webhook, tích hợp cổng khách hàng và tuân theo các thực tiễn tốt nhất của Go để giúp bạn bắt đầu chấp nhận thanh toán nhanh chóng.

<Info>
  Boilerplate này sử dụng Go 1.21+ với các mô hình kiến trúc sạch (`cmd`, `internal`, `templates`), các mẫu HTML và SDK `dodopayments-go` để tích hợp API mượt mà.
</Info>

### Tính năng

* **Khởi động nhanh** - Bắt đầu trong chưa đầy 5 phút
* **Tích hợp thanh toán** - Luồng thanh toán đã được cấu hình sẵn sử dụng SDK `dodopayments-go`
* **Giao diện hiện đại** - Trang giá chủ đề tối, sạch sẽ với các mẫu HTML
* **Xử lý webhook** - Xác thực và xử lý sự kiện thanh toán một cách an toàn
* **Cổng khách hàng** - Quản lý đăng ký tự phục vụ
* **Thực hành tốt Go** - Kiến trúc sạch với `cmd`, `internal` và `templates`
* **Thanh toán điền sẵn** - Minh họa việc truyền dữ liệu khách hàng để cải thiện trải nghiệm người dùng

## Điều kiện tiên quyết

Trước khi bạn bắt đầu, hãy đảm bảo bạn đã có:

* **Go 1.21+**
* **Tài khoản Dodo Payments** (để truy cập API và Webhook Keys từ bảng điều khiển)

## Bắt đầu nhanh

<Steps>
  <Step title="Clone the Repository">
    ```bash theme={null}
    git clone https://github.com/dodopayments/go-boilerplate.git
    cd go-boilerplate
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    make install
    ```

    Hoặc thủ công:

    ```bash theme={null}
    go mod download
    ```
  </Step>

  <Step title="Get API Credentials">
    Đăng ký tại [Dodo Payments](https://dodopayments.com/) và lấy thông tin đăng nhập từ bảng điều khiển:

    * **API Key:** [Bảng điều khiển → Nhà phát triển → API Keys](https://app.dodopayments.com/developer/api-keys)
    * **Webhook Key:** [Bảng điều khiển → Nhà phát triển → Webhooks](https://app.dodopayments.com/developer/webhooks)

    <Tip>
      Hãy đảm bảo bạn đang ở **Chế độ kiểm tra** trong lúc phát triển!
    </Tip>
  </Step>

  <Step title="Configure Environment Variables">
    Tạo một tệp `.env` trong thư mục gốc:

    ```bash theme={null}
    cp .env.example .env
    ```

    Cập nhật các giá trị với thông tin xác thực Dodo Payments của bạn:

    ```bash .env theme={null}
    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
    ```

    <Warning>
      Không bao giờ đưa tệp `.env` vào hệ thống kiểm soát phiên bản. Nó đã được bao gồm trong `.gitignore`.
    </Warning>
  </Step>

  <Step title="Add Your Products">
    Cập nhật `internal/lib/products.go` bằng các ID sản phẩm thực tế từ Dodo Payments:

    ```go theme={null}
    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
    }
    ```
  </Step>

  <Step title="Run the Development Server">
    ```bash theme={null}
    make run
    ```

    Hoặc thủ công:

    ```bash theme={null}
    go run cmd/server/main.go
    ```

    Mở [http://localhost:8000](http://localhost:8000) để xem trang giá của bạn!

    <Check>
      Bạn sẽ thấy một trang giá theo chủ đề tối với sản phẩm của mình đã sẵn sàng để mua.
    </Check>
  </Step>
</Steps>

## Cấu trúc dự án

```text theme={null}
go-boilerplate/
├── cmd/
│   └── server/             # Application entry point
├── internal/
│   ├── api/                # API handlers (Checkout, Portal, Webhook)
│   ├── core/               # Configuration and system core
│   └── lib/                # Shared logic (Products, Customer utils)
├── templates/              # HTML templates
├── Makefile                # Build and run commands
├── go.mod                  # Go module definition
├── go.sum                  # Dependency checksums
├── .env.example            # Environment template
└── README.md
```

## API Endpoints

Boilerplate bao gồm các điểm cuối được cấu hình sẵn sau:

| Endpoint               | Phương thức | Mô tả                            |
| ---------------------- | ----------- | -------------------------------- |
| `/`                    | GET         | Trang giá với danh sách sản phẩm |
| `/api/checkout`        | POST        | Tạo phiên thanh toán mới         |
| `/api/webhook`         | POST        | Xử lý webhook từ Dodo Payments   |
| `/api/customer-portal` | POST        | Tạo URL cổng khách hàng          |

## Tùy chỉnh

### Cập nhật thông tin sản phẩm

Chỉnh sửa `internal/lib/products.go` để tùy chỉnh:

* ID sản phẩm (từ bảng điều khiển Dodo của bạn)
* Giá
* Tính năng
* Mô tả

```go theme={null}
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",
        },
    },
}
```

### Tự động điền dữ liệu khách hàng

Trong `templates/index.html`, thay dữ liệu khách hàng mã hóa cứng bằng dữ liệu người dùng thực tế của bạn:

```javascript theme={null}
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
};
```

Trong một ứng dụng sản xuất, bạn sẽ tiêm động các giá trị này từ hệ thống xác thực của bạn.

## Sự kiện Webhook

Boilerplate minh họa cách xử lý các sự kiện webhook trong `internal/api/webhook.go`. Các sự kiện được hỗ trợ bao gồm:

| Sự kiện               | Mô tả                                       |
| --------------------- | ------------------------------------------- |
| `subscription.active` | Kích hoạt khi một đăng ký trở nên hoạt động |
| `payment.succeeded`   | Kích hoạt khi một thanh toán thành công     |

Thêm logic kinh doanh của bạn bên trong trình xử lý webhook để:

* Cập nhật quyền người dùng trong cơ sở dữ liệu của bạn
* Gửi email xác nhận
* Cung cấp quyền truy cập vào các sản phẩm kỹ thuật số
* Theo dõi phân tích và số liệu

## Kiểm tra Webhook Locally

Đối với phát triển cục bộ, sử dụng các công cụ như [ngrok](https://ngrok.com/) để mở rộng máy chủ cục bộ của bạn:

```bash theme={null}
ngrok http 8000
```

Cập nhật URL webhook trong [Bảng điều khiển Dodo Payments](https://app.dodopayments.com/developer/webhooks):

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

## Triển khai

### Xây dựng cho sản xuất

```bash theme={null}
make build
```

Hoặc thủ công:

```bash theme={null}
go build -o bin/server cmd/server/main.go
./bin/server
```

### Triển khai lên Vercel

\[

![Triển khai với Vercel](https://vercel.com/button)

]\([https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate](https://vercel.com/new/clone?repository-url=https://github.com/dodopayments/go-boilerplate))

### Docker

Tạo một `Dockerfile`:

```dockerfile theme={null}
FROM golang:1.21-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"]
```

Xây dựng và chạy:

```bash theme={null}
docker build -t go-dodo .
docker run -p 8000:8000 --env-file .env go-dodo
```

### Cân nhắc sản xuất

<Warning>
  Trước khi triển khai lên môi trường production:

  * Chuyển `DODO_PAYMENTS_ENVIRONMENT` sang `live_mode`
  * Sử dụng khóa API production từ bảng điều khiển
  * Cập nhật URL webhook thành miền production của bạn
  * Bật HTTPS cho tất cả các điểm cuối
</Warning>

## Khắc phục sự cố

<AccordionGroup>
  <Accordion title="Build errors or missing dependencies">
    Đảm bảo các module Go được tải xuống đúng cách:

    ```bash theme={null}
    go mod tidy
    go mod download
    ```
  </Accordion>

  <Accordion title="Checkout session creation fails">
    **Các nguyên nhân phổ biến:**

    * ID sản phẩm không hợp lệ - xác nhận nó tồn tại trong bảng điều khiển Dodo của bạn
    * Khóa API hoặc thiết lập môi trường sai trong `.env`
    * Kiểm tra nhật ký máy chủ để biết thông báo lỗi chi tiết
  </Accordion>

  <Accordion title="Webhooks not receiving events">
    Để thử nghiệm cục bộ, hãy dùng [ngrok](https://ngrok.com) để công khai máy chủ của bạn:

    ```bash theme={null}
    ngrok http 8000
    ```

    Cập nhật URL webhook trong [bảng điều khiển Dodo](https://app.dodopayments.com/developer/webhooks) của bạn thành URL ngrok. Hãy chắc là cập nhật tệp `.env` với khóa xác thực webhook chính xác.
  </Accordion>

  <Accordion title="Templates not loading">
    Đảm bảo bạn đang chạy máy chủ từ thư mục gốc của dự án, hoặc đường dẫn đến mẫu đã được cấu hình đúng trong mã của bạn.
  </Accordion>
</AccordionGroup>

## Tìm hiểu thêm

<CardGroup cols={2}>
  <Card title="Go SDK" icon="golang" href="/developer-resources/sdks/go">
    Tài liệu đầy đủ về Go SDK
  </Card>

  <Card title="Webhooks Documentation" icon="webhook" href="/developer-resources/webhooks">
    Tìm hiểu về tất cả sự kiện webhook và các thực hành tốt nhất
  </Card>

  <Card title="Checkout Sessions" icon="credit-card" href="/developer-resources/checkout-session">
    Đi sâu vào cấu hình phiên thanh toán
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Tài liệu đầy đủ về API Dodo Payments
  </Card>
</CardGroup>

## Hỗ trợ

Cần giúp đỡ với boilerplate?

* Tham gia cộng đồng [Discord của chúng tôi](https://discord.gg/bYqAp4ayYh) để đặt câu hỏi và thảo luận
* Kiểm tra [kho lưu trữ GitHub](https://github.com/dodopayments/go-boilerplate) để biết các vấn đề và cập nhật
* Liên hệ với [đội ngũ hỗ trợ của chúng tôi](mailto:support@dodopayments.com) để được trợ giúp