安装
使用 Go 模块安装 SDK：go get github.com/dodopayments/dodopayments-go
go get -u 'github.com/dodopayments/dodopayments-go@v1.97.3'
SDK 需要 Go 1.22 或更高版本，利用现代 Go 功能以实现最佳性能。
快速开始
初始化客户端并创建您的第一个结账会话：package main
import (
"context"
"fmt"
"log"
"github.com/dodopayments/dodopayments-go"
"github.com/dodopayments/dodopayments-go/option"
)
func main() {
client := dodopayments.NewClient(
option.WithBearerToken("My Bearer Token"), // defaults to os.LookupEnv("DODO_PAYMENTS_API_KEY")
option.WithEnvironmentTestMode(), // defaults to option.WithEnvironmentLiveMode()
)
checkoutSessionResponse, err := client.CheckoutSessions.New(context.TODO(), dodopayments.CheckoutSessionNewParams{
CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{{
ProductID: dodopayments.F("product_id"),
Quantity: dodopayments.F(int64(1)),
}}),
},
})
if err != nil {
panic(err.Error())
}
fmt.Printf("Session ID: %s\n", checkoutSessionResponse.SessionID)
}
始终使用环境变量安全地存储 API 密钥。切勿将它们硬编码在源代码中。
核心特性
Context Support
完全支持
context.Context，以处理取消和超时Strong Typing
强类型请求和响应，确保编译时安全性
Middleware
可扩展的中间件支持用于日志记录、指标和自定义逻辑
Goroutine Safe
为并发操作设计的线程安全客户端
配置
上下文和超时
利用 Go 的上下文进行超时和取消：import (
"context"
"time"
"github.com/dodopayments/dodopayments-go"
"github.com/dodopayments/dodopayments-go/option"
)
// Create a context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
payment, err := client.Payments.New(ctx, dodopayments.PaymentNewParams{
Billing: dodopayments.F(dodopayments.BillingAddressParam{
Country: dodopayments.F(dodopayments.CountryCodeUs),
City: dodopayments.F("San Francisco"),
State: dodopayments.F("CA"),
Street: dodopayments.F("1 Market St"),
Zipcode: dodopayments.F("94105"),
}),
Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
dodopayments.AttachExistingCustomerParam{
CustomerID: dodopayments.F("cus_123"),
},
),
ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
ProductID: dodopayments.F("pdt_456"),
Quantity: dodopayments.F(int64(1)),
}}),
})
if err != nil {
if ctx.Err() == context.DeadlineExceeded {
log.Println("Request timed out")
} else {
log.Fatal(err)
}
}
重试配置
配置自动重试行为：// Configure default for all requests (default is 2)
client := dodopayments.NewClient(
option.WithMaxRetries(0), // disable retries
)
// Override per-request
client.CheckoutSessions.New(
context.TODO(),
dodopayments.CheckoutSessionNewParams{
CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{{
ProductID: dodopayments.F("product_id"),
Quantity: dodopayments.F(int64(0)),
}}),
},
},
option.WithMaxRetries(5),
)
常见操作
创建结账会话
生成一个结账会话：session, err := client.CheckoutSessions.New(ctx, dodopayments.CheckoutSessionNewParams{
CheckoutSessionRequest: dodopayments.CheckoutSessionRequestParam{
ProductCart: dodopayments.F([]dodopayments.ProductItemReqParam{{
ProductID: dodopayments.F("pdt_123"),
Quantity: dodopayments.F(int64(1)),
}}),
ReturnURL: dodopayments.F("https://yourdomain.com/return"),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Checkout URL: %s\n", session.CheckoutURL)
管理客户
创建和检索客户信息：// Create a customer
customer, err := client.Customers.New(ctx, dodopayments.CustomerNewParams{
Email: dodopayments.F("customer@example.com"),
Name: dodopayments.F("John Doe"),
Metadata: dodopayments.F(map[string]string{
"user_id": "12345",
}),
})
if err != nil {
log.Fatal(err)
}
// Retrieve customer
customer, err = client.Customers.Get(ctx, "cus_123")
if err != nil {
log.Fatal(err)
}
fmt.Printf("Customer: %s (%s)\n", customer.Name, customer.Email)
处理订阅
创建和管理定期订阅：POST /subscriptions（SDK 的 subscriptions.create 方法）已弃用。对于现有集成，它仍然有效，但新集成应通过 Checkout Session 创建订阅。import "time"
// Create a subscription
subscription, err := client.Subscriptions.New(ctx, dodopayments.SubscriptionNewParams{
Billing: dodopayments.F(dodopayments.BillingAddressParam{
Country: dodopayments.F(dodopayments.CountryCodeUs),
City: dodopayments.F("San Francisco"),
State: dodopayments.F("CA"),
Street: dodopayments.F("1 Market St"),
Zipcode: dodopayments.F("94105"),
}),
Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
dodopayments.AttachExistingCustomerParam{
CustomerID: dodopayments.F("cus_123"),
},
),
ProductID: dodopayments.F("pdt_456"),
Quantity: dodopayments.F(int64(1)),
})
if err != nil {
log.Fatal(err)
}
// Charge an on-demand subscription
// ProductPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
chargeResponse, err := client.Subscriptions.Charge(ctx, subscription.SubscriptionID,
dodopayments.SubscriptionChargeParams{
ProductPrice: dodopayments.F(int64(2500)),
},
)
if err != nil {
log.Fatal(err)
}
// Get usage history (for metered subscriptions)
usageHistory, err := client.Subscriptions.GetUsageHistory(
ctx,
subscription.SubscriptionID,
dodopayments.SubscriptionGetUsageHistoryParams{
StartDate: dodopayments.F(time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)),
EndDate: dodopayments.F(time.Date(2024, 3, 31, 23, 59, 59, 0, time.UTC)),
},
)
if err != nil {
log.Fatal(err)
}
Billing 至少需要两位字母的 ISO Country 代码。Customer 是一个 CustomerRequestUnionParam — 对于现有客户，请传入 AttachExistingCustomerParam{CustomerID: ...}；对于新客户，请传入 NewCustomerParam{Email: ..., Name: ...}。ProductPrice 使用货币的最小面额。基于用量的计费
摄取用量事件
跟踪自定义事件：import "github.com/dodopayments/dodopayments-go"
response, err := client.UsageEvents.Ingest(ctx, dodopayments.UsageEventIngestParams{
Events: dodopayments.F([]dodopayments.EventInputParam{{
EventID: dodopayments.F("api_call_12345"),
CustomerID: dodopayments.F("cus_abc123"),
EventName: dodopayments.F("api_request"),
Timestamp: dodopayments.F(time.Date(2024, 1, 15, 10, 30, 0, 0, time.UTC)),
}}),
})
if err != nil {
log.Fatal(err)
}
列出用量事件
// List events with filters
params := dodopayments.UsageEventListParams{
CustomerID: dodopayments.F("cus_abc123"),
EventName: dodopayments.F("api_request"),
}
events, err := client.UsageEvents.List(ctx, params)
if err != nil {
log.Fatal(err)
}
for _, event := range events.Items {
fmt.Printf("Event %s: %s at %s\n", event.EventID, event.EventName, event.Timestamp)
}
错误处理
当 API 返回非成功状态码时，SDK 会返回*dodopayments.Error 类型的错误。它会公开 StatusCode、底层的 *http.Request 和
*http.Response，以及错误正文的 JSON。使用 errors.As 模式检查错误，并根据 StatusCode 分支处理特定情况：
payment, err := client.Payments.New(ctx, dodopayments.PaymentNewParams{
Billing: dodopayments.F(dodopayments.BillingAddressParam{
Country: dodopayments.F(dodopayments.CountryCodeUs),
City: dodopayments.F("San Francisco"),
State: dodopayments.F("CA"),
Street: dodopayments.F("1 Market St"),
Zipcode: dodopayments.F("94105"),
}),
Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
dodopayments.AttachExistingCustomerParam{CustomerID: dodopayments.F("cus_123")},
),
ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
ProductID: dodopayments.F("pdt_456"),
Quantity: dodopayments.F(int64(1)),
}}),
})
if err != nil {
var apiErr *dodopayments.Error
if errors.As(err, &apiErr) {
fmt.Printf("Status Code: %d\n", apiErr.StatusCode)
fmt.Println(string(apiErr.DumpResponse(true))) // Serialized HTTP response
// Handle specific status codes
switch apiErr.StatusCode {
case 401:
log.Println("Authentication failed")
case 422:
log.Println("Invalid request parameters")
case 429:
log.Println("Rate limit exceeded")
default:
log.Printf("API error: %s", apiErr.Error())
}
} else {
log.Fatal(err)
}
}
中间件
添加用于日志记录或指标收集的自定义中间件：func Logger(req *http.Request, next option.MiddlewareNext) (res *http.Response, err error) {
// Before the request
start := time.Now()
log.Printf("Request: %s %s\n", req.Method, req.URL)
// Forward the request to the next handler
res, err = next(req)
// After the request
end := time.Now()
log.Printf("Response: %d in %v\n", res.StatusCode, end.Sub(start))
return res, err
}
client := dodopayments.NewClient(
option.WithMiddleware(Logger),
)
并发
客户端可安全地并发使用：package main
import (
"context"
"sync"
"log"
"github.com/dodopayments/dodopayments-go"
)
func main() {
client := dodopayments.NewClient()
var wg sync.WaitGroup
for i := 0; i < 10; i++ {
wg.Add(1)
go func(idx int) {
defer wg.Done()
payment, err := client.Payments.New(context.Background(), dodopayments.PaymentNewParams{
Billing: dodopayments.F(dodopayments.BillingAddressParam{
Country: dodopayments.F(dodopayments.CountryCodeUs),
City: dodopayments.F("San Francisco"),
State: dodopayments.F("CA"),
Street: dodopayments.F("1 Market St"),
Zipcode: dodopayments.F("94105"),
}),
Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](
dodopayments.AttachExistingCustomerParam{CustomerID: dodopayments.F("cus_123")},
),
ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
ProductID: dodopayments.F("pdt_456"),
Quantity: dodopayments.F(int64(1)),
}}),
})
if err != nil {
log.Printf("Failed to create payment %d: %v", idx, err)
return
}
log.Printf("Created payment %d: %s", idx, payment.PaymentID)
}(i)
}
wg.Wait()
}
资源
GitHub Repository
查看源代码并参与贡献
API Reference
完整的 API 文档
Discord Community
获取帮助并与开发者交流
Report Issues
报告错误或请求功能
支持
需要 Go SDK 方面的帮助？- Discord：加入我们的社区服务器获取实时支持
- Email：通过 support@dodopayments.com 联系我们
- GitHub：在代码仓库中提交 issue