Go - Dodo Payments Documentation

Go SDKは、Dodo Paymentsをアプリケーションに統合するためのクリーンで慣用的なGoインターフェースを提供します。コンテキストサポート、強く型付けされたレスポンス、ミドルウェア機能を提供し、同時使用に安全です。

インストール

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 には、少なくとも2文字の 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)
	}
}

Middleware

ロギングやメトリクス用のカスタム Middleware を追加します:

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: リアルタイムのサポートを受けるには、コミュニティサーバーに参加してください
メール: support@dodopayments.com までお問い合わせください
GitHub: リポジトリで issue を作成してください

コントリビューション

コントリビューションを歓迎します！始めるには、コントリビューションガイドラインを確認してください。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

インストール

クイックスタート

コア機能

Context Support

Strong Typing

Middleware

Goroutine Safe

設定

コンテキストとタイムアウト

リトライ設定

一般的な操作

チェックアウトセッションの作成

顧客の管理

サブスクリプションの管理

使用量ベースの請求

使用量イベントの取り込み

使用量イベントの一覧表示

エラーハンドリング

Middleware

並行性

リソース

GitHub Repository

API Reference

Discord Community

Report Issues

サポート

コントリビューション

​インストール

​クイックスタート

​コア機能

Context Support

Strong Typing

Middleware

Goroutine Safe

​設定

​コンテキストとタイムアウト

​リトライ設定

​一般的な操作

​チェックアウトセッションの作成

​顧客の管理

​サブスクリプションの管理

​使用量ベースの請求

​使用量イベントの取り込み

​使用量イベントの一覧表示

​エラーハンドリング

​Middleware

​並行性

​リソース

GitHub Repository

API Reference

Discord Community

Report Issues

​サポート

​コントリビューション

インストール

クイックスタート

コア機能

設定

コンテキストとタイムアウト

リトライ設定

一般的な操作

チェックアウトセッションの作成

顧客の管理

サブスクリプションの管理

使用量ベースの請求

使用量イベントの取り込み

使用量イベントの一覧表示

エラーハンドリング

Middleware

並行性

リソース

サポート

コントリビューション