Go - Dodo Payments Documentation

L’SDK Go fornisce un’interfaccia Go pulita e idiomatica per integrare Dodo Payments nelle tue applicazioni. Offre supporto per il contesto, risposte fortemente tipizzate, capacità di middleware ed è sicuro per l’uso concorrente.

Installazione

Installa l’SDK utilizzando i moduli Go:

go get github.com/dodopayments/dodopayments-go

Oppure per fissare a una versione specifica:

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

L’SDK richiede Go 1.22 o versioni successive, sfruttando le funzionalità moderne di Go per prestazioni ottimali.

Avvio Veloce

Inizializza il client e crea la tua prima sessione di checkout:

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

Memorizza sempre le chiavi API in modo sicuro utilizzando le variabili d’ambiente. Non inserirle mai direttamente nel codice sorgente.

Caratteristiche Principali

Context Support

Supporto completo per context.Context per annullamenti e timeout

Strong Typing

Richieste e risposte fortemente tipizzate per la sicurezza a tempo di compilazione

Middleware

Supporto per middleware estendibili per logging, metriche e logica personalizzata

Goroutine Safe

Client thread-safe progettato per operazioni concorrenti

Configurazione

Contesto e Timeout

Sfrutta il contesto di Go per timeout e cancellazione:

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

Configurazione del Retry

Configura il comportamento di retry automatico:

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

Operazioni Comuni

Crea una Sessione di Checkout

Genera una sessione di checkout:

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)

Gestisci i Clienti

Crea e recupera informazioni sui clienti:

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

Gestisci Abbonamenti

Crea e gestisci abbonamenti ricorrenti:

POST /subscriptions (the SDK’s subscriptions.create method) è deprecato. Continua a funzionare per le integrazioni esistenti, ma per le nuove integrazioni è necessario creare abbonamenti tramite una 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 richiede almeno il codice ISO di due lettere Country. Customer è un CustomerRequestUnionParam — passare AttachExistingCustomerParam{CustomerID: ...} per un cliente esistente o NewCustomerParam{Email: ..., Name: ...} per uno nuovo. ProductPrice è espresso nella denominazione più bassa della valuta.

Fatturazione basata sull’utilizzo

Acquisizione degli eventi di utilizzo

Traccia eventi personalizzati:

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

Elenco degli eventi di utilizzo

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

Gestione degli errori

Quando l’API restituisce un codice di stato non relativo a un’operazione riuscita, l’SDK restituisce un errore di tipo *dodopayments.Error. Espone StatusCode, *http.Request sottostante e *http.Response, oltre al JSON del corpo dell’errore. Usa il pattern errors.As per ispezionarlo e usa StatusCode per gestire casi specifici:

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

Middleware

Aggiungi middleware personalizzato per il logging o le metriche:

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

Concorrenza

Il client è sicuro per l’utilizzo concorrente:

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

Risorse

GitHub Repository

Visualizza il codice sorgente e contribuisci

API Reference

Documentazione completa dell’API

Discord Community

Ricevi assistenza e connettiti con altri sviluppatori

Report Issues

Segnala bug o richiedi funzionalità

Supporto

Hai bisogno di assistenza con l’SDK Go?

Discord: Unisciti al nostro server della community per ricevere assistenza in tempo reale
Email: Contattaci all’indirizzo support@dodopayments.com
GitHub: Apri una segnalazione nel repository

Contribuire

Accogliamo con piacere i contributi! Consulta le linee guida per i contributi per iniziare.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

Installazione

Avvio Veloce

Caratteristiche Principali

Context Support

Strong Typing

Middleware

Goroutine Safe

Configurazione

Contesto e Timeout

Configurazione del Retry

Operazioni Comuni

Crea una Sessione di Checkout

Gestisci i Clienti

Gestisci Abbonamenti

Fatturazione basata sull’utilizzo

Acquisizione degli eventi di utilizzo

Elenco degli eventi di utilizzo

Gestione degli errori

Middleware

Concorrenza

Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

Supporto

Contribuire

​Installazione

​Avvio Veloce

​Caratteristiche Principali

Context Support

Strong Typing

Middleware

Goroutine Safe

​Configurazione

​Contesto e Timeout

​Configurazione del Retry

​Operazioni Comuni

​Crea una Sessione di Checkout

​Gestisci i Clienti

​Gestisci Abbonamenti

​Fatturazione basata sull’utilizzo

​Acquisizione degli eventi di utilizzo

​Elenco degli eventi di utilizzo

​Gestione degli errori

​Middleware

​Concorrenza

​Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

​Supporto

​Contribuire

Installazione

Avvio Veloce

Caratteristiche Principali

Configurazione

Contesto e Timeout

Configurazione del Retry

Operazioni Comuni

Crea una Sessione di Checkout

Gestisci i Clienti

Gestisci Abbonamenti

Fatturazione basata sull’utilizzo

Acquisizione degli eventi di utilizzo

Elenco degli eventi di utilizzo

Gestione degli errori

Middleware

Concorrenza

Risorse

Supporto

Contribuire