Go - Dodo Payments Documentation

Go SDK ger Go-applikationer typad åtkomst till Dodo Payments REST API. Varje metod tar en context.Context, request-parametrar använder en Field-wrapper som skiljer nollvärden från utelämnade fält, och du kan lägga till middleware i varje request.

Installation

Lägg till modulen i ditt projekt:

go get github.com/dodopayments/dodopayments-go

Så här låser du till en specifik version:

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

SDK:t kräver Go 1.22 eller senare.

Snabbstart

Skapa en klient och skapa sedan en 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)
}

Om du utelämnar option.WithBearerToken läser NewClient miljövariabeln DODO_PAYMENTS_API_KEY. Om du utelämnar option.WithEnvironmentTestMode() ansluter klienten till live mode. En API-nyckel för testläge fungerar endast i testläge.

Förvara API-nycklar i miljövariabler eller en secrets manager. Hårdkoda dem aldrig i källkoden.

Kärnfunktioner

Context Support

Varje metod tar en context.Context för avbrytning och timeouts.

Strong Typing

Typade request-parametrar och response-strukturer för kontroller vid kompilering.

Middleware

Lägg till middleware med option.WithMiddleware för loggning, mätvärden och anpassad logik.

Goroutine Safe

Dela en klient mellan goroutines.

Konfiguration

NewClient läser DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY (din webhook signing secret) och DODO_PAYMENTS_BASE_URL från miljön. Alternativ som du skickar in, till exempel option.WithBearerToken, option.WithWebhookKey och option.WithBaseURL, åsidosätter dem. Om du vill verifiera en webhook skickar du requestens råa body och headers till client.Webhooks.Unwrap(rawBody, r.Header). Den kontrollerar signaturen med din webhook-nyckel och returnerar den tolkade händelsen. client.Webhooks.UnsafeUnwrap(rawBody) tolkar bodyn utan att verifiera den, så använd den endast för testning. Se Webhooks. Exemplen på den här sidan använder client från Snabbstart.

Context och timeouts

Requests får ingen timeout som standard. En context-deadline begränsar hela anropet, inklusive retries. Om du vill begränsa varje försök lägger du till 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-konfiguration

SDK:t försöker igen vid anslutningsfel och svar med status 408, 409, 429 eller 500 och högre. Som standard görs två nya försök, med exponentiell backoff. Ange option.WithMaxRetries på klienten eller för en enskild 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),
)

Vanliga operationer

Exemplen i det här avsnittet använder också en context, till exempel ctx := context.Background().

Skapa en checkout-session

Skapa en checkout-session och omdirigera sedan kunden till den returnerade CheckoutURL:

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)

Varje checkout-URL fungerar en gång och upphör att gälla efter 24 timmar. Information om alla sessionsalternativ finns i Checkout Sessions.

Hantera kunder

Skapa en kund med en e-postadress och ett namn och hämta den sedan med ID. Metadata-värden använder unionstyperna från paketet 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)

Hantera prenumerationer

Skapa en prenumeration, debitera en on-demand-prenumeration och läs en prenumerations användningshistorik.

POST /subscriptions (SDK:ts Subscriptions.New-metod) är föråldrad. Den fungerar fortfarande för befintliga integrationer, men nya integrationer bör skapa prenumerationer via en 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 kräver endast Country, en tvåbokstavskod för ISO-land. Customer är en CustomerRequestUnionParam: skicka AttachExistingCustomerParam{CustomerID: ...} för en befintlig kund eller NewCustomerParam{Email: ..., Name: ...} för att skapa en. Charge används för on-demand-prenumerationer, och ProductPrice anges i den minsta valutaenheten. GetUsageHistory returnerar en resultatsida; GetUsageHistoryAutoPaging itererar över alla sidor.

Förbrukningsbaserad fakturering

Ta emot användningshändelser

Skicka användningshändelser för en kund:

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 är idempotency key, så ge varje händelse ett unikt värde. Om samma EventID förekommer två gånger i en request avvisas hela requesten. Om en EventID redan har tagits emot ignoreras den nya händelsen. En request accepterar upp till 1 000 händelser. Timestamp använder aktuell tid som standard och avvisas om den ligger mer än 1 timme bakåt eller mer än 5 minuter framåt i tiden.

Lista användningshändelser

Lista händelser filtrerade efter kund och händelsenamn:

// 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 returnerar en sida. Om du vill iterera över alla sidor anropar du client.UsageEvents.ListAutoPaging(ctx, params) och loopar med iter.Next(), iter.Current() och iter.Err(). Andra listmetoder har samma AutoPaging-variant, och varje sida har en GetNextPage()-metod.

Felhantering

När API:et returnerar en statuskod som inte anger framgång returnerar SDK:t ett fel av typen *dodopayments.Error. Det innehåller StatusCode, *http.Request och *http.Response samt JSON från felbodyn. Använd errors.As för att granska det och gör en förgrening på StatusCode för att hantera specifika fall:

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

Andra fel returneras utan wrapper. Om HTTP-transporten till exempel misslyckas kan du få en *url.Error som omsluter en *net.OpError. apiErr.DumpRequest(true) returnerar den serialiserade requesten.

Middleware

Lägg till middleware med option.WithMiddleware. En middleware tar emot varje request och en next-funktion som skickar den vidare:

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

Flera middleware i ett anrop till option.WithMiddleware körs från vänster till höger. Middleware som skickas till NewClient körs före middleware som skickas till en enskild request.

Samtidighet

Klienten är säker att använda samtidigt, så du kan dela en klient mellan goroutines:

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

Resurser

GitHub Repository

Källkod, releaser och den fullständiga metodlistan.

API Reference

Alla endpoints, parametrar och svar.

Discord Community

Ställ frågor och prata med andra utvecklare.

Report Issues

Rapportera buggar eller föreslå funktioner.

Support

Om du behöver hjälp med Go SDK:

Discord: Gå med i community-servern för hjälp i realtid.
E-post: Kontakta support@dodopayments.com.
GitHub: Skapa ett ärende i kodförvaret.

Bidra

Om du vill bidra kan du läsa riktlinjerna för bidrag.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

Installation

Snabbstart

Kärnfunktioner

Context Support

Strong Typing

Middleware

Goroutine Safe

Konfiguration

Context och timeouts

Retry-konfiguration

Vanliga operationer

Skapa en checkout-session

Hantera kunder

Hantera prenumerationer

Förbrukningsbaserad fakturering

Ta emot användningshändelser

Lista användningshändelser

Felhantering

Middleware

Samtidighet

Resurser

GitHub Repository

API Reference

Discord Community

Report Issues

Support

Bidra

​Installation

​Snabbstart

​Kärnfunktioner

Context Support

Strong Typing

Middleware

Goroutine Safe

​Konfiguration

​Context och timeouts

​Retry-konfiguration

​Vanliga operationer

​Skapa en checkout-session

​Hantera kunder

​Hantera prenumerationer

​Förbrukningsbaserad fakturering

​Ta emot användningshändelser

​Lista användningshändelser

​Felhantering

​Middleware

​Samtidighet

​Resurser

GitHub Repository

API Reference

Discord Community

Report Issues

​Support

​Bidra

Installation

Snabbstart

Kärnfunktioner

Konfiguration

Context och timeouts

Retry-konfiguration

Vanliga operationer

Skapa en checkout-session

Hantera kunder

Hantera prenumerationer

Förbrukningsbaserad fakturering

Ta emot användningshändelser

Lista användningshändelser

Felhantering

Middleware

Samtidighet

Resurser

Support

Bidra