Go - Dodo Payments Documentation

Go SDKを使用すると、GoアプリケーションからDodo Payments REST APIに型付きでアクセスできます。すべてのメソッドはcontext.Contextを受け取り、リクエストパラメータでは、ゼロ値と省略されたフィールドを区別するFieldラッパーを使用します。また、すべてのリクエストにmiddlewareを追加できます。

インストール

モジュールをプロジェクトに追加します。

go get github.com/dodopayments/dodopayments-go

特定のバージョンに固定するには、次のようにします。

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

SDKにはGo 1.22以降が必要です。

クイックスタート

clientを作成し、その後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)
}

option.WithBearerTokenを省略すると、NewClientは環境変数DODO_PAYMENTS_API_KEYを読み取ります。option.WithEnvironmentTestMode()を省略すると、clientはlive modeに接続します。test modeのAPI keyはtest modeでのみ使用できます。

API keyは環境変数またはsecrets managerで管理してください。ソースコードに直接記述しないでください。

主な機能

Context Support

すべてのメソッドは、キャンセルとタイムアウトに対応するcontext.Contextを受け取ります。

Strong Typing

コンパイル時チェックに対応した、型付きのリクエストパラメータとレスポンスstructを使用できます。

Middleware

ロギング、メトリクス、カスタムロジックのためにoption.WithMiddlewareでmiddlewareを追加できます。

Goroutine Safe

複数のgoroutineで1つのclientを共有できます。

設定

NewClientは、環境変数からDODO_PAYMENTS_API_KEY、DODO_PAYMENTS_WEBHOOK_KEY（webhook signing secret）、およびDODO_PAYMENTS_BASE_URLを読み取ります。option.WithBearerToken、option.WithWebhookKey、option.WithBaseURLなど、渡したオプションはこれらの値を上書きします。 webhookを検証するには、未加工のリクエストボディとheadersをclient.Webhooks.Unwrap(rawBody, r.Header)に渡します。webhook keyを使用してsignatureを確認し、解析済みのeventを返します。client.Webhooks.UnsafeUnwrap(rawBody)は検証せずにbodyを解析するため、テスト時にのみ使用してください。Webhooksを参照してください。このページの例では、Quick Startのclientを使用しています。

Contextとタイムアウト

リクエストにはデフォルトでタイムアウトが設定されていません。contextのdeadlineは、リトライを含む呼び出し全体を制限します。各試行を制限するには、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)
	}
}

リトライ設定

SDKは、connection errorと、status 408、409、429、または500以上のresponseをリトライします。デフォルトでは、exponential backoffを使用して2回リトライします。clientまたは単一のリクエストにoption.WithMaxRetriesを設定します。

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

一般的な操作

このセクションの例でもcontextを使用します。たとえばctx := context.Background()です。

Checkout Sessionの作成

checkout sessionを作成し、返されたCheckoutURLにcustomerをリダイレクトします。

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)

各checkout URLは1回だけ使用でき、24時間後に有効期限が切れます。すべてのsession optionについては、Checkout Sessionsを参照してください。

Customerの管理

email addressとnameを指定してcustomerを作成し、IDで取得します。Metadataの値には、shared packageのunion typeを使用します。

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)

Subscriptionの処理

subscriptionを作成し、on-demand subscriptionに課金し、subscriptionのusage historyを読み取ります。

POST /subscriptions（SDKのSubscriptions.Newメソッド）は非推奨です。既存のintegrationでは引き続き動作しますが、新しいintegrationではCheckout Sessionを通じてsubscriptionを作成してください。

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に必要なのは、2文字のISO country codeであるCountryだけです。CustomerはCustomerRequestUnionParamです。既存のcustomerにはAttachExistingCustomerParam{CustomerID: ...}を渡し、新しく作成する場合はNewCustomerParam{Email: ..., Name: ...}を渡します。Chargeはon-demand subscriptions用で、ProductPriceは通貨の最小単位で指定します。GetUsageHistoryは結果の1ページを返し、GetUsageHistoryAutoPagingはすべてのページを反復処理します。

使用量ベースのBilling

Usage Eventの取り込み

customerのusage eventを送信します。

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はidempotency keyなので、各eventに一意の値を指定してください。同じEventIDが1つのリクエスト内に2回現れると、リクエスト全体が拒否されます。EventIDがすでに取り込まれている場合、新しいeventは無視されます。1回のリクエストで最大1,000件のeventを受け付けます。Timestampのデフォルト値は現在時刻で、過去1時間より前、または未来5分より後の値は拒否されます。

Usage Eventの一覧表示

customerとevent nameでフィルタリングした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は1ページを返します。すべてのページを反復処理するには、client.UsageEvents.ListAutoPaging(ctx, params)を呼び出し、iter.Next()、iter.Current()、iter.Err()を使ってループします。その他のlist methodにも同じAutoPaging variantがあり、各ページにはGetNextPage() methodがあります。

Error Handling

APIがsuccess以外のstatus codeを返すと、SDKは*dodopayments.Error型のerrorを返します。このerrorにはStatusCode、*http.Request、*http.Response、およびerror bodyのJSONが含まれます。errors.Asを使用して内容を確認し、StatusCodeに基づいて分岐し、特定のケースを処理します。

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

その他のerrorはラップされずに返されます。たとえば、HTTP transportが失敗した場合、*net.OpErrorをラップした*url.Errorを受け取ることがあります。apiErr.DumpRequest(true)はserialized requestを返します。

Middleware

option.WithMiddlewareを使用してmiddlewareを追加します。middlewareは各リクエストと、そのリクエストを送信するnext functionを受け取ります。

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

1回のoption.WithMiddleware呼び出しに複数のmiddlewareを指定すると、左から右の順に実行されます。NewClientに渡したmiddlewareは、単一のリクエストに渡したmiddlewareより前に実行されます。

Concurrency

clientはconcurrent useに対応しているため、複数のgoroutineで1つのclientを共有できます。

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

リソース

GitHub Repository

ソースコード、リリース、および完全なmethod list。

API Reference

すべてのendpoint、parameter、response。

Discord Community

質問したり、他のdeveloperと交流したりできます。

Report Issues

bugの報告やfeatureのリクエストを行えます。

サポート

Go SDKについてサポートが必要な場合：

Discord：community serverに参加して、リアルタイムでサポートを受けてください。
Email：support@dodopayments.comまでお問い合わせください。
GitHub：repositoryでissueを作成してください。

Contributing

貢献するには、contributing guidelinesをお読みください。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

インストール

クイックスタート

主な機能

Context Support

Strong Typing

Middleware

Goroutine Safe

設定

Contextとタイムアウト

リトライ設定

一般的な操作

Checkout Sessionの作成

Customerの管理

Subscriptionの処理

使用量ベースのBilling

Usage Eventの取り込み

Usage Eventの一覧表示

Error Handling

Middleware

Concurrency

リソース

GitHub Repository

API Reference

Discord Community

Report Issues

サポート

Contributing

​インストール

​クイックスタート

​主な機能

Context Support

Strong Typing

Middleware

Goroutine Safe

​設定

​Contextとタイムアウト

​リトライ設定

​一般的な操作

​Checkout Sessionの作成

​Customerの管理

​Subscriptionの処理

​使用量ベースのBilling

​Usage Eventの取り込み

​Usage Eventの一覧表示

​Error Handling

​Middleware

​Concurrency

​リソース

GitHub Repository

API Reference

Discord Community

Report Issues

​サポート

​Contributing

インストール

クイックスタート

主な機能

設定

Contextとタイムアウト

リトライ設定

一般的な操作

Checkout Sessionの作成

Customerの管理

Subscriptionの処理

使用量ベースのBilling

Usage Eventの取り込み

Usage Eventの一覧表示

Error Handling

Middleware

Concurrency

リソース

サポート

Contributing