Go - Dodo Payments Documentation

Go SDK는 Go 애플리케이션에서 Dodo Payments REST API에 타입이 지정된 방식으로 액세스할 수 있도록 합니다. 모든 메서드는 context.Context를 인수로 받고, 요청 매개변수는 0 값을 생략된 필드와 구분하는 Field 래퍼를 사용하며, 모든 요청에 middleware를 추가할 수 있습니다.

설치

프로젝트에 모듈을 추가합니다:

go get github.com/dodopayments/dodopayments-go

특정 버전을 고정하려면:

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

SDK를 사용하려면 Go 1.22 이상이 필요합니다.

빠른 시작

클라이언트를 생성한 다음 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()를 생략하면 클라이언트는 live mode에 연결됩니다. test mode API key는 test mode에서만 사용할 수 있습니다.

API key는 환경 변수 또는 secrets manager에 보관하세요. 소스 코드에 절대 하드코딩하지 마세요.

핵심 기능

Context Support

모든 메서드는 취소 및 timeout을 위한 context.Context를 인수로 받습니다.

Strong Typing

컴파일 시 검사를 지원하는 타입이 지정된 요청 매개변수 및 응답 struct를 제공합니다.

Middleware

로깅, 메트릭 및 사용자 지정 로직을 위해 option.WithMiddleware를 사용하여 middleware를 추가합니다.

Goroutine Safe

여러 goroutine에서 하나의 클라이언트를 공유합니다.

구성

NewClient는 환경 변수에서 DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY(웹훅 서명 secret), DODO_PAYMENTS_BASE_URL를 읽습니다. option.WithBearerToken, option.WithWebhookKey, option.WithBaseURL와 같이 전달하는 옵션은 해당 값을 재정의합니다. 웹훅을 확인하려면 원시 요청 본문과 headers를 client.Webhooks.Unwrap(rawBody, r.Header)에 전달합니다. 이 메서드는 웹훅 key로 signature를 확인하고 파싱된 event를 반환합니다. client.Webhooks.UnsafeUnwrap(rawBody)는 확인 없이 본문을 파싱하므로 테스트에만 사용하세요. Webhooks를 참조하세요. 이 페이지의 예제에서는 빠른 시작의 client를 사용합니다.

Context 및 Timeout

요청은 기본적으로 timeout되지 않습니다. 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)
	}
}

Retry 구성

SDK는 connection error와 상태 코드가 408, 409, 429 또는 500 이상인 response를 재시도합니다. 기본적으로 exponential backoff를 사용하여 두 번 재시도합니다. 클라이언트 또는 단일 요청에 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로 고객을 redirect합니다:

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은 한 번만 작동하며 24시간 후 만료됩니다. 모든 session 옵션은 Checkout Sessions를 참조하세요.

고객 관리

email 주소와 이름으로 고객을 생성한 다음 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 메서드)은 deprecated입니다. 기존 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에는 두 글자로 된 ISO 국가 코드인 Country만 필요합니다. Customer는 CustomerRequestUnionParam입니다. 기존 고객에는 AttachExistingCustomerParam{CustomerID: ...}를 전달하고, 새 고객을 생성하려면 NewCustomerParam{Email: ..., Name: ...}를 전달합니다. Charge는 on-demand subscriptions에 사용되며, ProductPrice는 통화의 최소 단위로 표시됩니다. GetUsageHistory는 결과의 한 페이지를 반환하고, GetUsageHistoryAutoPaging는 모든 페이지를 순회합니다.

사용량 기반 Billing

Usage Event 수집

고객의 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가 하나의 요청에 두 번 나타나면 요청 전체가 거부됩니다. EventID가 이미 수집된 경우 새 event는 무시됩니다. 하나의 요청에는 최대 1,000개의 event를 포함할 수 있습니다. Timestamp는 현재 시간으로 기본 설정되며, 1시간보다 이전이거나 5분보다 이후인 경우 거부됩니다.

Usage Event 목록 조회

고객 및 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는 한 페이지를 반환합니다. 모든 페이지를 순회하려면 client.UsageEvents.ListAutoPaging(ctx, params)를 호출하고 iter.Next(), iter.Current(), iter.Err()를 사용하여 loop를 실행합니다. 다른 list 메서드에도 동일한 AutoPaging variant가 있으며, 각 페이지에는 GetNextPage() 메서드가 있습니다.

Error 처리

API가 성공하지 않은 status code를 반환하면 SDK는 *dodopayments.Error type의 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)는 직렬화된 요청을 반환합니다.

Middleware

option.WithMiddleware를 사용하여 middleware를 추가합니다. middleware는 각 요청과 해당 요청을 전송하는 next 함수를 받습니다:

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

하나의 option.WithMiddleware 호출에 전달된 여러 middleware는 왼쪽에서 오른쪽 순서로 실행됩니다. NewClient에 전달된 middleware는 단일 요청에 전달된 middleware보다 먼저 실행됩니다.

동시성

클라이언트는 동시 사용에 안전하므로 여러 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()
}

리소스

GitHub Repository

소스 코드, release 및 전체 메서드 목록입니다.

API Reference

모든 endpoint, 매개변수 및 response입니다.

Discord Community

질문하고 다른 개발자와 소통하세요.

Report Issues

bug를 보고하거나 feature를 요청하세요.

Support

Go SDK에 대한 도움이 필요하면 다음을 이용하세요:

Discord: 실시간 도움을 받으려면 community server에 참여하세요.
Email: support@dodopayments.com으로 문의하세요.
GitHub: repository에 issue를 등록하세요.

기여

기여하려면 contributing guidelines를 읽어보세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

설치

빠른 시작

핵심 기능

Context Support

Strong Typing

Middleware

Goroutine Safe

구성

Context 및 Timeout

Retry 구성

일반적인 작업

Checkout Session 생성

고객 관리

Subscription 처리

사용량 기반 Billing

Usage Event 수집

Usage Event 목록 조회

Error 처리

Middleware

동시성

리소스

GitHub Repository

API Reference

Discord Community

Report Issues

Support

기여

​설치

​빠른 시작

​핵심 기능

Context Support

Strong Typing

Middleware

Goroutine Safe

​구성

​Context 및 Timeout

​Retry 구성

​일반적인 작업

​Checkout Session 생성

​고객 관리

​Subscription 처리

​사용량 기반 Billing

​Usage Event 수집

​Usage Event 목록 조회

​Error 처리

​Middleware

​동시성

​리소스

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​기여

설치

빠른 시작

핵심 기능

구성

Context 및 Timeout

Retry 구성

일반적인 작업

Checkout Session 생성

고객 관리

Subscription 처리

사용량 기반 Billing

Usage Event 수집

Usage Event 목록 조회

Error 처리

Middleware

동시성

리소스

Support

기여