Go - Dodo Payments Documentation

SDK Go cung cấp một giao diện Go sạch sẽ và theo phong cách cho việc tích hợp Dodo Payments vào các ứng dụng của bạn. Nó hỗ trợ ngữ cảnh, phản hồi kiểu mạnh, khả năng middleware và an toàn cho việc sử dụng đồng thời.

Cài đặt

Cài đặt SDK bằng cách sử dụng Go modules:

go get github.com/dodopayments/dodopayments-go

Hoặc để gán cho một phiên bản cụ thể:

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

SDK yêu cầu Go 1.22 hoặc các phiên bản mới hơn, tận dụng các tính năng hiện đại của Go để đạt hiệu suất tối ưu.

Bắt đầu nhanh

Khởi tạo client và tạo phiên checkout đầu tiên của bạn:

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

Luôn lưu trữ khóa API của bạn một cách an toàn bằng cách sử dụng biến môi trường. Không bao giờ mã hóa cứng chúng trong mã nguồn.

Tính năng chính

Context Support

Hỗ trợ đầy đủ cho context.Context đối với việc hủy và hết thời gian chờ

Strong Typing

Các yêu cầu và phản hồi kiểu mạnh để đảm bảo an toàn tại thời gian biên dịch

Middleware

Hỗ trợ middleware mở rộng cho ghi nhật ký, số liệu và logic tùy chỉnh

Goroutine Safe

Client an toàn luồng được thiết kế cho các thao tác đồng thời

Cấu hình

Context và Thời gian chờ

Tận dụng context của Go cho thời gian chờ và hủy bỏ:

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

Cấu hình Retry

Cấu hình hành vi tự động thử lại:

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

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

Tạo một phiên Checkout

Tạo một phiên checkout:

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)

Quản lý Khách hàng

Tạo và truy xuất thông tin khách hàng:

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

Xử lý Đăng ký

Tạo và quản lý các đăng ký định kỳ:

POST /subscriptions (phương thức subscriptions.create của SDK) đã không còn được dùng. Phương thức này vẫn hoạt động với các integration hiện có, nhưng integration mới nên tạo subscription thông qua 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 yêu cầu tối thiểu mã ISO gồm hai chữ cái Country. Customer là một CustomerRequestUnionParam — truyền AttachExistingCustomerParam{CustomerID: ...} cho customer hiện có hoặc NewCustomerParam{Email: ..., Name: ...} cho customer mới. ProductPrice được tính theo đơn vị tiền tệ nhỏ nhất.

Tính phí theo mức sử dụng

Tiếp nhận sự kiện sử dụng

Theo dõi các sự kiện tùy chỉnh:

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

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

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

Xử lý lỗi

Khi API trả về mã trạng thái không thành công, SDK trả về một lỗi thuộc kiểu *dodopayments.Error. Lỗi này cung cấp StatusCode, *http.Request bên dưới và *http.Response, cùng với JSON của nội dung lỗi. Sử dụng mẫu errors.As để kiểm tra lỗi, và rẽ nhánh dựa trên StatusCode để xử lý các trường hợp cụ thể:

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

Middleware

Thêm middleware tùy chỉnh để ghi log hoặc thu thập metrics:

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),
)

Tính đồng thời

Client an toàn khi được sử dụng đồng thời:

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

Tài nguyên

GitHub Repository

Xem mã nguồn và đóng góp

API Reference

Tài liệu API đầy đủ

Discord Community

Nhận trợ giúp và kết nối với các developer

Report Issues

Báo lỗi hoặc yêu cầu tính năng

Hỗ trợ

Bạn cần trợ giúp về Go SDK?

Discord: Tham gia community server của chúng tôi để nhận hỗ trợ theo thời gian thực
Email: Liên hệ với chúng tôi qua support@dodopayments.com
GitHub: Mở issue trên repository

Đóng góp

Chúng tôi hoan nghênh các đóng góp! Hãy xem hướng dẫn đóng góp để bắt đầu.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

Cài đặt

Bắt đầu nhanh

Tính năng chính

Context Support

Strong Typing

Middleware

Goroutine Safe

Cấu hình

Context và Thời gian chờ

Cấu hình Retry

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

Tạo một phiên Checkout

Quản lý Khách hàng

Xử lý Đăng ký

Tính phí theo mức sử dụng

Tiếp nhận sự kiện sử dụng

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

Xử lý lỗi

Middleware

Tính đồ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 chính

Context Support

Strong Typing

Middleware

Goroutine Safe

​Cấu hình

​Context và Thời gian chờ

​Cấu hình Retry

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

​Tạo một phiên Checkout

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

​Xử lý Đăng ký

​Tính phí theo mức sử dụng

​Tiếp nhận sự kiện sử dụng

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

​Xử lý lỗi

​Middleware

​Tính đồ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 chính

Cấu hình

Context và Thời gian chờ

Cấu hình Retry

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

Tạo một phiên Checkout

Quản lý Khách hàng

Xử lý Đăng ký

Tính phí theo mức sử dụng

Tiếp nhận sự kiện sử dụng

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

Xử lý lỗi

Middleware

Tính đồng thời

Tài nguyên

Hỗ trợ

Đóng góp