Go - Dodo Payments Documentation

Go SDK menyediakan akses bertipe untuk aplikasi Go ke REST API Dodo Payments. Setiap metode menerima context.Context, parameter request menggunakan wrapper Field yang membedakan zero value dari field yang dihilangkan, dan Anda dapat menambahkan middleware ke setiap request.

Instalasi

Tambahkan modul ke project Anda:

go get github.com/dodopayments/dodopayments-go

Untuk menetapkan versi tertentu:

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

SDK memerlukan Go 1.22 atau yang lebih baru.

Memulai dengan Cepat

Buat client, lalu buat 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)
}

Jika Anda tidak menyertakan option.WithBearerToken, NewClient membaca environment variable DODO_PAYMENTS_API_KEY. Jika Anda tidak menyertakan option.WithEnvironmentTestMode(), client terhubung ke live mode. API key test mode hanya berfungsi dalam test mode.

Simpan API key dalam environment variable atau secrets manager. Jangan pernah menuliskannya secara hardcode dalam source code.

Fitur Utama

Context Support

Setiap metode menerima context.Context untuk cancellation dan timeout.

Strong Typing

Parameter request dan struct response bertipe untuk pemeriksaan saat compile time.

Middleware

Tambahkan middleware dengan option.WithMiddleware untuk logging, metrics, dan logika khusus.

Goroutine Safe

Gunakan satu client bersama di beberapa goroutine.

Konfigurasi

NewClient membaca DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY (webhook signing secret Anda), dan DODO_PAYMENTS_BASE_URL dari environment. Opsi yang Anda teruskan, seperti option.WithBearerToken, option.WithWebhookKey, dan option.WithBaseURL, akan menimpanya. Untuk memverifikasi webhook, teruskan raw request body dan header ke client.Webhooks.Unwrap(rawBody, r.Header). Fungsi ini memeriksa signature dengan webhook key Anda dan mengembalikan event yang telah di-parse. client.Webhooks.UnsafeUnwrap(rawBody) mem-parse body tanpa memverifikasinya, jadi gunakan hanya untuk testing. Lihat Webhooks. Contoh di halaman ini menggunakan client dari Quick Start.

Context dan Timeout

Request tidak memiliki timeout secara default. Deadline context membatasi seluruh call, termasuk retry. Untuk membatasi setiap attempt, tambahkan 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)
	}
}

Konfigurasi Retry

SDK melakukan retry untuk connection error dan response dengan status 408, 409, 429, atau 500 ke atas. Secara default, SDK melakukan retry dua kali dengan exponential backoff. Tetapkan option.WithMaxRetries pada client atau satu request:

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

Operasi Umum

Contoh di bagian ini juga menggunakan context, misalnya ctx := context.Background().

Membuat Checkout Session

Buat checkout session, lalu redirect customer ke CheckoutURL yang dikembalikan:

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)

Setiap checkout URL hanya dapat digunakan sekali dan kedaluwarsa setelah 24 jam. Untuk setiap opsi session, lihat Checkout Sessions.

Mengelola Customer

Buat customer dengan alamat email dan nama, lalu ambil kembali berdasarkan ID. Nilai metadata menggunakan union type dari package shared:

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)

Menangani Subscription

Buat subscription, charge subscription on-demand, dan baca riwayat penggunaan subscription.

POST /subscriptions (metode Subscriptions.New milik SDK) deprecated. Metode ini masih berfungsi untuk integrasi yang sudah ada, tetapi integrasi baru sebaiknya membuat subscription melalui 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)
}
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 hanya memerlukan Country, yaitu kode negara ISO dua huruf. Customer adalah CustomerRequestUnionParam: teruskan AttachExistingCustomerParam{CustomerID: ...} untuk customer yang sudah ada atau NewCustomerParam{Email: ..., Name: ...} untuk membuat customer baru. Charge digunakan untuk on-demand subscriptions, dan ProductPrice menggunakan unit mata uang terkecil. GetUsageHistory mengembalikan satu halaman hasil; GetUsageHistoryAutoPaging melakukan iterasi pada setiap halaman.

Usage-Based Billing

Memasukkan Usage Event

Kirim usage event untuk customer:

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 adalah idempotency key, jadi berikan nilai unik untuk setiap event. Jika EventID yang sama muncul dua kali dalam satu request, seluruh request akan ditolak. Jika EventID sudah pernah di-ingest, event baru akan diabaikan. Satu request dapat menerima hingga 1.000 event. Timestamp secara default menggunakan waktu saat ini dan akan ditolak jika lebih dari 1 jam di masa lalu atau lebih dari 5 menit di masa mendatang.

Mencantumkan Usage Event

Cantumkan event yang difilter berdasarkan customer dan nama 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 mengembalikan satu halaman. Untuk melakukan iterasi pada setiap halaman, panggil client.UsageEvents.ListAutoPaging(ctx, params) dan lakukan loop dengan iter.Next(), iter.Current(), dan iter.Err(). Metode list lainnya memiliki varian AutoPaging yang sama, dan setiap halaman memiliki metode GetNextPage().

Penanganan Error

Saat API mengembalikan status code non-success, SDK mengembalikan error bertipe *dodopayments.Error. Error ini memiliki StatusCode, *http.Request dan *http.Response, serta JSON dari error body. Gunakan errors.As untuk memeriksanya, lalu buat percabangan berdasarkan StatusCode untuk menangani kasus tertentu:

// 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 lainnya dikembalikan tanpa pembungkus. Misalnya, jika HTTP transport gagal, Anda mungkin menerima *url.Error yang membungkus *net.OpError. apiErr.DumpRequest(true) mengembalikan request yang telah diserialisasi.

Middleware

Tambahkan middleware dengan option.WithMiddleware. Middleware menerima setiap request dan fungsi next yang mengirimkannya:

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

Beberapa middleware dalam satu pemanggilan option.WithMiddleware dijalankan dari kiri ke kanan. Middleware yang diteruskan ke NewClient dijalankan sebelum middleware yang diteruskan ke satu request.

Concurrency

Client aman digunakan secara concurrent, sehingga Anda dapat menggunakan satu client bersama di beberapa 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()
}

Resource

GitHub Repository

Source code, release, dan daftar metode lengkap.

API Reference

Setiap endpoint, parameter, dan response.

Discord Community

Ajukan pertanyaan dan berdiskusi dengan developer lain.

Report Issues

Laporkan bug atau minta fitur.

Dukungan

Untuk mendapatkan bantuan terkait Go SDK:

Discord: Bergabunglah dengan community server untuk mendapatkan bantuan secara real-time.
Email: Hubungi support@dodopayments.com.
GitHub: Buka issue di repository.

Kontribusi

Untuk berkontribusi, baca contributing guidelines.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

Instalasi

Memulai dengan Cepat

Fitur Utama

Context Support

Strong Typing

Middleware

Goroutine Safe

Konfigurasi

Context dan Timeout

Konfigurasi Retry

Operasi Umum

Membuat Checkout Session

Mengelola Customer

Menangani Subscription

Usage-Based Billing

Memasukkan Usage Event

Mencantumkan Usage Event

Penanganan Error

Middleware

Concurrency

Resource

GitHub Repository

API Reference

Discord Community

Report Issues

Dukungan

Kontribusi

​Instalasi

​Memulai dengan Cepat

​Fitur Utama

Context Support

Strong Typing

Middleware

Goroutine Safe

​Konfigurasi

​Context dan Timeout

​Konfigurasi Retry

​Operasi Umum

​Membuat Checkout Session

​Mengelola Customer

​Menangani Subscription

​Usage-Based Billing

​Memasukkan Usage Event

​Mencantumkan Usage Event

​Penanganan Error

​Middleware

​Concurrency

​Resource

GitHub Repository

API Reference

Discord Community

Report Issues

​Dukungan

​Kontribusi

Instalasi

Memulai dengan Cepat

Fitur Utama

Konfigurasi

Context dan Timeout

Konfigurasi Retry

Operasi Umum

Membuat Checkout Session

Mengelola Customer

Menangani Subscription

Usage-Based Billing

Memasukkan Usage Event

Mencantumkan Usage Event

Penanganan Error

Middleware

Concurrency

Resource

Dukungan

Kontribusi