Go - Dodo Payments Documentation

Le SDK Go permet aux applications Go d’accéder de manière typée à l’API REST de Dodo Payments. Chaque méthode accepte un context.Context, les paramètres de requête utilisent un wrapper Field qui sépare les valeurs nulles des champs omis, et vous pouvez ajouter du middleware à chaque requête.

Installation

Ajoutez le module à votre projet :

go get github.com/dodopayments/dodopayments-go

Pour verrouiller une version spécifique :

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

Le SDK nécessite Go 1.22 ou une version ultérieure.

Démarrage rapide

Créez un client, puis créez une session de paiement :

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

Si vous omettez option.WithBearerToken, NewClient lit la variable d’environnement DODO_PAYMENTS_API_KEY. Si vous omettez option.WithEnvironmentTestMode(), le client se connecte au mode live. Une clé API de test fonctionne uniquement en mode test.

Conservez les clés API dans des variables d’environnement ou un gestionnaire de secrets. Ne les codez jamais en dur dans votre code source.

Fonctionnalités principales

Context Support

Chaque méthode accepte un context.Context pour l’annulation et les délais d’expiration.

Strong Typing

Paramètres de requête et structures de réponse typés pour effectuer des vérifications à la compilation.

Middleware

Ajoutez du middleware avec option.WithMiddleware pour la journalisation, les métriques et la logique personnalisée.

Goroutine Safe

Partagez un même client entre plusieurs goroutines.

Configuration

NewClient lit DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY (votre secret de signature des webhooks) et DODO_PAYMENTS_BASE_URL depuis l’environnement. Les options que vous transmettez, telles que option.WithBearerToken, option.WithWebhookKey et option.WithBaseURL, les remplacent. Pour vérifier un webhook, transmettez le corps brut de la requête et les en-têtes à client.Webhooks.Unwrap(rawBody, r.Header). Cette fonction vérifie la signature avec votre clé de webhook et renvoie l’événement analysé. client.Webhooks.UnsafeUnwrap(rawBody) analyse le corps sans le vérifier ; utilisez-la donc uniquement pour les tests. Consultez Webhooks. Les exemples de cette page utilisent le client de Démarrage rapide.

Contextes et délais d’expiration

Les requêtes n’expirent pas par défaut. Une échéance de contexte limite l’appel complet, y compris les nouvelles tentatives. Pour limiter chaque tentative, ajoutez 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)
	}
}

Configuration des nouvelles tentatives

Le SDK réessaie les erreurs de connexion et les réponses dont le statut est 408, 409, 429 ou 500 et supérieur. Par défaut, il effectue deux nouvelles tentatives avec un backoff exponentiel. Définissez option.WithMaxRetries sur le client ou sur une seule requête :

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

Opérations courantes

Les exemples de cette section utilisent également un contexte, par exemple ctx := context.Background().

Créer une session de paiement

Créez une session de paiement, puis redirigez le client vers le CheckoutURL renvoyé :

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)

Chaque URL de paiement ne fonctionne qu’une seule fois et expire après 24 heures. Pour connaître toutes les options de session, consultez Sessions de paiement.

Gérer les clients

Créez un client avec une adresse e-mail et un nom, puis récupérez-le par son ID. Les valeurs de métadonnées utilisent les types union du 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)

Gérer les abonnements

Créez un abonnement, facturez un abonnement à la demande et consultez l’historique d’utilisation d’un abonnement.

POST /subscriptions (la méthode Subscriptions.New du SDK) est obsolète. Elle fonctionne toujours pour les intégrations existantes, mais les nouvelles intégrations doivent créer des abonnements via une session de paiement.

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 nécessite uniquement Country, un code pays ISO à deux lettres. Customer est un CustomerRequestUnionParam : transmettez AttachExistingCustomerParam{CustomerID: ...} pour un client existant ou NewCustomerParam{Email: ..., Name: ...} pour en créer un. Charge est destiné aux abonnements à la demande, et ProductPrice est exprimé dans la plus petite unité monétaire. GetUsageHistory renvoie une page de résultats ; GetUsageHistoryAutoPaging parcourt toutes les pages.

Facturation basée sur l’utilisation

Ingérer des événements d’utilisation

Envoyez des événements d’utilisation pour un client :

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)

Le EventID est la clé d’idempotence ; attribuez donc une valeur unique à chaque événement. Si le même EventID apparaît deux fois dans une même requête, l’ensemble de la requête est rejeté. Si un EventID a déjà été ingéré, le nouvel événement est ignoré. Une requête accepte jusqu’à 1 000 événements. Timestamp prend par défaut l’heure actuelle et est rejeté s’il date de plus d’une heure ou s’il est situé à plus de 5 minutes dans le futur.

Répertorier les événements d’utilisation

Répertoriez les événements filtrés par client et par nom d’événement :

// 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 renvoie une page. Pour parcourir toutes les pages, appelez client.UsageEvents.ListAutoPaging(ctx, params) et effectuez une boucle avec iter.Next(), iter.Current() et iter.Err(). Les autres méthodes de liste disposent de la même variante AutoPaging, et chaque page possède une méthode GetNextPage().

Gestion des erreurs

Lorsque l’API renvoie un code d’état de non-réussite, le SDK renvoie une erreur de type *dodopayments.Error. Elle contient StatusCode, *http.Request et *http.Response, ainsi que le JSON du corps de l’erreur. Utilisez errors.As pour l’inspecter, et utilisez StatusCode dans une condition pour gérer des cas spécifiques :

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

Les autres erreurs sont renvoyées sans wrapper. Par exemple, si le transport HTTP échoue, vous pouvez recevoir un *url.Error qui encapsule un *net.OpError. apiErr.DumpRequest(true) renvoie la requête sérialisée.

Middleware

Ajoutez du middleware avec option.WithMiddleware. Un middleware reçoit chaque requête ainsi qu’une fonction next qui l’envoie :

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

Plusieurs middlewares dans un même appel option.WithMiddleware s’exécutent de gauche à droite. Les middlewares transmis à NewClient s’exécutent avant ceux transmis à une requête donnée.

Concurrence

Le client peut être utilisé simultanément en toute sécurité ; vous pouvez donc partager un même client entre plusieurs 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()
}

Ressources

GitHub Repository

Code source, versions et liste complète des méthodes.

API Reference

Chaque endpoint, paramètre et réponse.

Discord Community

Posez vos questions et échangez avec d’autres développeurs.

Report Issues

Signalez des bugs ou demandez des fonctionnalités.

Assistance

Pour obtenir de l’aide avec le SDK Go :

Discord : rejoignez le serveur communautaire pour obtenir de l’aide en temps réel.
E-mail : contactez support@dodopayments.com.
GitHub : ouvrez un ticket dans le dépôt.

Contribuer

Pour contribuer, consultez les directives de contribution.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

Installation

Démarrage rapide

Fonctionnalités principales

Context Support

Strong Typing

Middleware

Goroutine Safe

Configuration

Contextes et délais d’expiration

Configuration des nouvelles tentatives

Opérations courantes

Créer une session de paiement

Gérer les clients

Gérer les abonnements

Facturation basée sur l’utilisation

Ingérer des événements d’utilisation

Répertorier les événements d’utilisation

Gestion des erreurs

Middleware

Concurrence

Ressources

GitHub Repository

API Reference

Discord Community

Report Issues

Assistance

Contribuer

​Installation

​Démarrage rapide

​Fonctionnalités principales

Context Support

Strong Typing

Middleware

Goroutine Safe

​Configuration

​Contextes et délais d’expiration

​Configuration des nouvelles tentatives

​Opérations courantes

​Créer une session de paiement

​Gérer les clients

​Gérer les abonnements

​Facturation basée sur l’utilisation

​Ingérer des événements d’utilisation

​Répertorier les événements d’utilisation

​Gestion des erreurs

​Middleware

​Concurrence

​Ressources

GitHub Repository

API Reference

Discord Community

Report Issues

​Assistance

​Contribuer

Installation

Démarrage rapide

Fonctionnalités principales

Configuration

Contextes et délais d’expiration

Configuration des nouvelles tentatives

Opérations courantes

Créer une session de paiement

Gérer les clients

Gérer les abonnements

Facturation basée sur l’utilisation

Ingérer des événements d’utilisation

Répertorier les événements d’utilisation

Gestion des erreurs

Middleware

Concurrence

Ressources

Assistance

Contribuer