Go - Dodo Payments Documentation

Go SDK cung cấp cho các ứng dụng Go quyền truy cập có kiểu tới REST API của Dodo Payments. Mỗi phương thức nhận một context.Context, các tham số request sử dụng wrapper Field để phân biệt các giá trị zero với các trường bị bỏ qua, và bạn có thể thêm middleware vào mọi request.

Cài đặt

Thêm module vào project của bạn:

go get github.com/dodopayments/dodopayments-go

Để cố định một phiên bản cụ thể:

go get -u 'github.com/dodopayments/dodopayments-go@v1.118.0'

SDK yêu cầu Go 1.22 trở lên.

Bắt đầu nhanh

Tạo client, sau đó tạo một checkout session:

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/dodopayments/dodopayments-go"
	"github.com/dodopayments/dodopayments-go/option"
)

func main() {
	client := dodopayments.NewClient(
		option.WithBearerToken(os.Getenv("DODO_PAYMENTS_API_KEY")), // This is the default and can be omitted
		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("pdt_123"),
				Quantity:  dodopayments.F(int64(1)),
			}}),
		},
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("Session ID: %s\n", checkoutSessionResponse.SessionID)
}

Nếu bạn bỏ qua option.WithBearerToken, NewClient sẽ đọc biến môi trường DODO_PAYMENTS_API_KEY. Nếu bạn bỏ qua option.WithEnvironmentTestMode(), client sẽ kết nối tới live mode. API key của test mode chỉ hoạt động trong test mode.

Lưu API key trong biến môi trường hoặc trình quản lý secrets. Không bao giờ hardcode chúng trong source code.

Tính năng cốt lõi

Context Support

Mỗi phương thức nhận một context.Context để hủy và thiết lập timeout.

Strong Typing

Các tham số request và struct response có kiểu để kiểm tra tại thời điểm biên dịch.

Middleware

Thêm middleware với option.WithMiddleware để ghi log, thu thập metrics và xử lý logic tùy chỉnh.

Goroutine Safe

Chia sẻ một client giữa các goroutine.

Cấu hình

NewClient đọc DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY (webhook signing secret của bạn) và DODO_PAYMENTS_BASE_URL từ môi trường. Các tùy chọn bạn truyền vào, chẳng hạn như option.WithBearerToken, option.WithWebhookKey và option.WithBaseURL, sẽ ghi đè các giá trị đó. Để xác minh webhook, truyền raw request body và headers tới client.Webhooks.Unwrap(rawBody, r.Header). Phương thức này kiểm tra signature bằng webhook key của bạn và trả về event đã được parse. client.Webhooks.UnsafeUnwrap(rawBody) parse body mà không xác minh, vì vậy chỉ sử dụng nó để testing. Xem Webhooks. Các ví dụ trên trang này sử dụng client từ Quick Start.

Context và timeout

Theo mặc định, request không có timeout. Deadline của context giới hạn toàn bộ lời gọi, bao gồm cả retry. Để giới hạn từng lần thử, thêm option.WithRequestTimeout():

import (
	"context"
	"log"
	"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()

// Note: POST /payments is deprecated — prefer checkout sessions for new
// integrations. Shown here only to illustrate context handling.
_, 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)),
	}}),
}, option.WithRequestTimeout(5*time.Second)) // Per-attempt timeout
if err != nil {
	if ctx.Err() == context.DeadlineExceeded {
		log.Println("Request timed out")
	} else {
		log.Fatal(err)
	}
}

Cấu hình retry

SDK retry các lỗi kết nối và các response có status 408, 409, 429 hoặc từ 500 trở lên. Theo mặc định, SDK retry hai lần với exponential backoff. Đặt option.WithMaxRetries trên client hoặc trên một request riêng lẻ:

// 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("pdt_123"),
				Quantity:  dodopayments.F(int64(1)),
			}}),
		},
	},
	option.WithMaxRetries(5),
)

Các thao tác phổ biến

Các ví dụ trong phần này cũng sử dụng context, chẳng hạn như ctx := context.Background().

Tạo Checkout Session

Tạo một checkout session, sau đó chuyển hướng khách hàng tới CheckoutURL được trả về:

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)

Mỗi checkout URL chỉ hoạt động một lần và hết hạn sau 24 giờ. Để xem mọi tùy chọn của session, hãy xem Checkout Sessions.

Quản lý khách hàng

Tạo một khách hàng với địa chỉ email và tên, sau đó truy xuất khách hàng theo ID. Các giá trị metadata sử dụng union type từ package shared:

import "github.com/dodopayments/dodopayments-go/shared"

// 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(dodopayments.MetadataParam{
		"user_id": shared.UnionString("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)

Xử lý subscription

Tạo một subscription, tính phí cho một on-demand subscription và đọc lịch sử sử dụng của subscription.

POST /subscriptions (phương thức Subscriptions.New của SDK) đã deprecated. Phương thức này vẫn hoạt động cho các integration hiện có, nhưng integration mới nên tạo subscription thông qua một 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)
}
fmt.Printf("Payment ID: %s\n", chargeResponse.PaymentID)

// 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)
}
fmt.Printf("Usage periods on this page: %d\n", len(usageHistory.Items))

Billing chỉ yêu cầu Country, là mã quốc gia ISO gồm hai chữ cái. Customer là một CustomerRequestUnionParam: truyền AttachExistingCustomerParam{CustomerID: ...} cho khách hàng hiện có hoặc NewCustomerParam{Email: ..., Name: ...} để tạo khách hàng mới. Charge dành cho on-demand subscriptions, còn ProductPrice được tính theo đơn vị nhỏ nhất của loại tiền tệ. GetUsageHistory trả về một trang kết quả; GetUsageHistoryAutoPaging lặp qua mọi trang.

Tính phí dựa trên mức sử dụng

Nạp sự kiện sử dụng

Gửi các sự kiện sử dụng cho một khách hàng:

import (
	"time"

	"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.Now()),
	}}),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Ingested %d events\n", response.IngestedCount)

EventID là idempotency key, vì vậy hãy cung cấp một giá trị duy nhất cho mỗi event. Nếu cùng một EventID xuất hiện hai lần trong một request, toàn bộ request sẽ bị từ chối. Nếu một EventID đã được ingest trước đó, event mới sẽ bị bỏ qua. Một request chấp nhận tối đa 1.000 event. Timestamp mặc định là thời điểm hiện tại và sẽ bị từ chối nếu sớm hơn hiện tại quá 1 giờ hoặc muộn hơn hiện tại quá 5 phút.

Liệt kê sự kiện sử dụng

Liệt kê các event được lọc theo khách hàng và tên event:

// 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)
}

List trả về một trang. Để lặp qua mọi trang, hãy gọi client.UsageEvents.ListAutoPaging(ctx, params) và lặp với iter.Next(), iter.Current() và iter.Err(). Các phương thức list khác cũng có biến thể AutoPaging tương tự, và mỗi trang có phương thức GetNextPage().

Xử lý lỗi

Khi API trả về status code không thành công, SDK trả về một error có type *dodopayments.Error. Error này có StatusCode, *http.Request và *http.Response, cùng JSON của error body. Sử dụng errors.As để kiểm tra error, và rẽ nhánh dựa trên StatusCode để xử lý các trường hợp cụ thể:

// Note: POST /payments is deprecated — prefer checkout sessions for new
// integrations. Shown here only to illustrate error handling.
_, 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)
	}
}

Các error khác được trả về mà không bọc. Ví dụ, nếu HTTP transport thất bại, bạn có thể nhận được một *url.Error bọc một *net.OpError. apiErr.DumpRequest(true) trả về request đã được serialize.

Middleware

Thêm middleware bằng option.WithMiddleware. Middleware nhận mỗi request và một function next để gửi request đó:

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 (res is nil when err is not nil)
	if err != nil {
		log.Printf("Request failed after %v: %v\n", time.Since(start), err)
		return res, err
	}
	log.Printf("Response: %d in %v\n", res.StatusCode, time.Since(start))

	return res, err
}

client := dodopayments.NewClient(
	option.WithMiddleware(Logger),
)

Nhiều middleware trong một lời gọi option.WithMiddleware sẽ chạy từ trái sang phải. Middleware được truyền vào NewClient sẽ chạy trước middleware được truyền vào một request riêng lẻ.

Đồng thời

Client an toàn khi sử dụng đồng thời, vì vậy bạn có thể chia sẻ một client giữa các goroutine:

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()
			
			// Note: POST /payments is deprecated — prefer checkout sessions
			// for new integrations. Shown here only to illustrate concurrency.
			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()
}

Tài nguyên

GitHub Repository

Source code, các bản phát hành và danh sách đầy đủ các phương thức.

API Reference

Mọi endpoint, tham số và response.

Discord Community

Đặt câu hỏi và trao đổi với các developer khác.

Report Issues

Báo cáo bug hoặc yêu cầu tính năng.

Hỗ trợ

Để được hỗ trợ về Go SDK:

Discord: Tham gia community server để nhận hỗ trợ theo thời gian thực.
Email: Liên hệ support@dodopayments.com.
GitHub: Mở issue trong repository.

Đóng góp

Để đóng góp, hãy đọc hướng dẫn đóng góp.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

Cài đặt

Bắt đầu nhanh

Tính năng cốt lõi

Context Support

Strong Typing

Middleware

Goroutine Safe

Cấu hình

Context và timeout

Cấu hình retry

Các thao tác phổ biến

Tạo Checkout Session

Quản lý khách hàng

Xử lý subscription

Tính phí dựa trên mức sử dụng

Nạp sự kiện sử dụng

Liệt kê sự kiện sử dụng

Xử lý lỗi

Middleware

Đồng thời

Tài nguyên

GitHub Repository

API Reference

Discord Community

Report Issues

Hỗ trợ

Đóng góp

​Cài đặt

​Bắt đầu nhanh

​Tính năng cốt lõi

Context Support

Strong Typing

Middleware

Goroutine Safe

​Cấu hình

​Context và timeout

​Cấu hình retry

​Các thao tác phổ biến

​Tạo Checkout Session

​Quản lý khách hàng

​Xử lý subscription

​Tính phí dựa trên mức sử dụng

​Nạp sự kiện sử dụng

​Liệt kê sự kiện sử dụng

​Xử lý lỗi

​Middleware

​Đồng thời

​Tài nguyên

GitHub Repository

API Reference

Discord Community

Report Issues

​Hỗ trợ

​Đóng góp

Cài đặt

Bắt đầu nhanh

Tính năng cốt lõi

Cấu hình

Context và timeout

Cấu hình retry

Các thao tác phổ biến

Tạo Checkout Session

Quản lý khách hàng

Xử lý subscription

Tính phí dựa trên mức sử dụng

Nạp sự kiện sử dụng

Liệt kê sự kiện sử dụng

Xử lý lỗi

Middleware

Đồng thời

Tài nguyên

Hỗ trợ

Đóng góp