Go - Dodo Payments Documentation

Il Go SDK consente alle applicazioni Go di accedere con tipi definiti alla REST API di Dodo Payments. Ogni metodo accetta un context.Context, i parametri delle richieste usano un wrapper Field che distingue i valori zero dai campi omessi e puoi aggiungere middleware a ogni richiesta.

Installazione

Aggiungi il modulo al progetto:

go get github.com/dodopayments/dodopayments-go

Per fissare una versione specifica:

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

Il SDK richiede Go 1.22 o versioni successive.

Avvio Veloce

Crea un client, quindi crea una 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)
}

Se ometti option.WithBearerToken, NewClient legge la variabile d’ambiente DODO_PAYMENTS_API_KEY. Se ometti option.WithEnvironmentTestMode(), il client si connette alla modalità live. Una API key della modalità test funziona solo in modalità test.

Conserva le API key nelle variabili d’ambiente o in un secrets manager. Non inserirle mai direttamente nel codice sorgente.

Funzionalità principali

Context Support

Ogni metodo accetta un context.Context per la cancellazione e i timeout.

Strong Typing

Parametri delle richieste e struct delle risposte tipizzati per i controlli in fase di compilazione.

Middleware

Aggiungi middleware con option.WithMiddleware per logging, metriche e logica personalizzata.

Goroutine Safe

Condividi un unico client tra le goroutine.

Configurazione

NewClient legge dall’ambiente DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY (il tuo webhook signing secret) e DODO_PAYMENTS_BASE_URL. Le opzioni che passi, come option.WithBearerToken, option.WithWebhookKey e option.WithBaseURL, hanno la precedenza su questi valori. Per verificare un webhook, passa il body grezzo della richiesta e gli header a client.Webhooks.Unwrap(rawBody, r.Header). Il metodo controlla la signature con la tua webhook key e restituisce l’evento analizzato. client.Webhooks.UnsafeUnwrap(rawBody) analizza il body senza verificarlo, quindi usalo solo per i test. Vedi Webhooks. Gli esempi in questa pagina usano client di Quick Start.

Context e timeout

Per impostazione predefinita, le richieste non hanno un timeout. Una deadline del context limita l’intera chiamata, inclusi i retries. Per limitare ogni tentativo, aggiungi 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)
	}
}

Configurazione dei retries

Il SDK ripete le richieste in caso di errori di connessione e di risposte con status 408, 409, 429 o 500 e superiori. Per impostazione predefinita esegue due retries, con exponential backoff. Imposta option.WithMaxRetries sul client o su una singola richiesta:

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

Operazioni comuni

Anche gli esempi di questa sezione usano un context, ad esempio ctx := context.Background().

Creare una Checkout Session

Crea una checkout session, quindi reindirizza il customer all’CheckoutURL restituito:

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)

Ogni checkout URL funziona una sola volta e scade dopo 24 ore. Per tutte le opzioni della sessione, vedi Checkout Sessions.

Gestire i customers

Crea un customer con un indirizzo email e un nome, quindi recuperalo tramite ID. I valori dei metadata usano i union types del 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)

Gestire le subscriptions

Crea una subscription, addebita una subscription on-demand e leggi la cronologia d’uso di una subscription.

POST /subscriptions (il metodo Subscriptions.New del SDK) è deprecato. Continua a funzionare per le integrazioni esistenti, ma le nuove integrazioni devono creare le subscriptions 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)
}
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 richiede solo Country, un codice paese ISO di due lettere. Customer è un CustomerRequestUnionParam: passa AttachExistingCustomerParam{CustomerID: ...} per un customer esistente oppure NewCustomerParam{Email: ..., Name: ...} per crearne uno. Charge è destinato alle subscriptions on-demand, mentre ProductPrice è espresso nell’unità minima della valuta. GetUsageHistory restituisce una pagina di risultati; GetUsageHistoryAutoPaging scorre tutte le pagine.

Fatturazione basata sull’utilizzo

Acquisire usage events

Invia usage events per un 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 è la idempotency key, quindi assegna a ogni evento un valore univoco. Se lo stesso EventID compare due volte nella stessa richiesta, l’intera richiesta viene rifiutata. Se un EventID è già stato acquisito, il nuovo evento viene ignorato. Una richiesta accetta fino a 1.000 eventi. Timestamp utilizza per impostazione predefinita l’ora corrente e viene rifiutato se è antecedente di oltre 1 ora o successivo di oltre 5 minuti.

Elencare gli usage events

Elenca gli eventi filtrati per customer e nome dell’evento:

// 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 restituisce una pagina. Per scorrere tutte le pagine, chiama client.UsageEvents.ListAutoPaging(ctx, params) ed esegui un ciclo con iter.Next(), iter.Current() e iter.Err(). Gli altri metodi list hanno la stessa variante AutoPaging e ogni pagina dispone di un metodo GetNextPage().

Gestione degli errori

Quando l’API restituisce uno status code non di successo, il SDK restituisce un errore di tipo *dodopayments.Error. Contiene StatusCode, *http.Request e *http.Response, oltre al JSON del body dell’errore. Usa errors.As per esaminarlo e usa StatusCode per gestire casi specifici:

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

Gli altri errori vengono restituiti senza wrapper. Ad esempio, se il transport HTTP non riesce, potresti ricevere un *url.Error che contiene un *net.OpError. apiErr.DumpRequest(true) restituisce la richiesta serializzata.

Middleware

Aggiungi middleware con option.WithMiddleware. Un middleware riceve ogni richiesta e una funzione next che la invia:

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

Più middleware nella stessa chiamata option.WithMiddleware vengono eseguiti da sinistra a destra. Il middleware passato a NewClient viene eseguito prima del middleware passato a una singola richiesta.

Concorrenza

Il client è sicuro per l’uso concorrente, quindi puoi condividere un unico client tra le 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()
}

Risorse

GitHub Repository

Codice sorgente, release ed elenco completo dei metodi.

API Reference

Ogni endpoint, parametro e risposta.

Discord Community

Fai domande e parla con altri sviluppatori.

Report Issues

Segnala bug o richiedi funzionalità.

Supporto

Per assistenza con il Go SDK:

Discord: Unisciti al server della community per ricevere assistenza in tempo reale.
Email: Contatta support@dodopayments.com.
GitHub: Apri un issue nel repository.

Contribuire

Per contribuire, leggi le linee guida per i contributi.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

Installazione

Avvio Veloce

Funzionalità principali

Context Support

Strong Typing

Middleware

Goroutine Safe

Configurazione

Context e timeout

Configurazione dei retries

Operazioni comuni

Creare una Checkout Session

Gestire i customers

Gestire le subscriptions

Fatturazione basata sull’utilizzo

Acquisire usage events

Elencare gli usage events

Gestione degli errori

Middleware

Concorrenza

Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

Supporto

Contribuire

​Installazione

​Avvio Veloce

​Funzionalità principali

Context Support

Strong Typing

Middleware

Goroutine Safe

​Configurazione

​Context e timeout

​Configurazione dei retries

​Operazioni comuni

​Creare una Checkout Session

​Gestire i customers

​Gestire le subscriptions

​Fatturazione basata sull’utilizzo

​Acquisire usage events

​Elencare gli usage events

​Gestione degli errori

​Middleware

​Concorrenza

​Risorse

GitHub Repository

API Reference

Discord Community

Report Issues

​Supporto

​Contribuire

Installazione

Avvio Veloce

Funzionalità principali

Configurazione

Context e timeout

Configurazione dei retries

Operazioni comuni

Creare una Checkout Session

Gestire i customers

Gestire le subscriptions

Fatturazione basata sull’utilizzo

Acquisire usage events

Elencare gli usage events

Gestione degli errori

Middleware

Concorrenza

Risorse

Supporto

Contribuire