Go - Dodo Payments Documentation

Go SDK는 Dodo Payments를 애플리케이션에 통합하기 위한 깔끔하고 관용적인 Go 인터페이스를 제공합니다. 이 SDK는 컨텍스트 지원, 강력한 타입의 응답, 미들웨어 기능을 제공하며, 동시 사용에 안전합니다.

설치

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 메서드)는 deprecated 상태입니다. 기존 통합에서는 계속 작동하지만, 새로운 통합에서는 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에는 최소한 두 자리 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)
	}
}

미들웨어

로깅 또는 메트릭을 위한 사용자 지정 미들웨어를 추가합니다:

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: 실시간 지원을 받으려면 커뮤니티 서버에 참여하세요
Email: support@dodopayments.com으로 문의하세요
GitHub: repository에 이슈를 등록하세요

기여

기여를 환영합니다! 시작하려면 기여 가이드라인을 확인하세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

설치

빠른 시작

핵심 기능

Context Support

Strong Typing

Middleware

Goroutine Safe

구성

컨텍스트 및 타임아웃

재시도 구성

일반 작업

체크아웃 세션 생성

고객 관리

구독 처리

사용량 기반 결제

사용량 이벤트 수집

사용량 이벤트 나열

오류 처리

미들웨어

동시성

리소스

GitHub Repository

API Reference

Discord Community

Report Issues

지원

기여

​설치

​빠른 시작

​핵심 기능

Context Support

Strong Typing

Middleware

Goroutine Safe

​구성

​컨텍스트 및 타임아웃

​재시도 구성

​일반 작업

​체크아웃 세션 생성

​고객 관리

​구독 처리

​사용량 기반 결제

​사용량 이벤트 수집

​사용량 이벤트 나열

​오류 처리

​미들웨어

​동시성

​리소스

GitHub Repository

API Reference

Discord Community

Report Issues

​지원

​기여

설치

빠른 시작

핵심 기능

구성

컨텍스트 및 타임아웃

재시도 구성

일반 작업

체크아웃 세션 생성

고객 관리

구독 처리

사용량 기반 결제

사용량 이벤트 수집

사용량 이벤트 나열

오류 처리

미들웨어

동시성

리소스

지원

기여