Go - Dodo Payments Documentation

El SDK de Go proporciona una interfaz limpia e idiomática de Go para integrar Dodo Payments en tus aplicaciones. Ofrece soporte de contexto, respuestas fuertemente tipadas, capacidades de middleware y es seguro para uso concurrente.

Instalación

Instala el SDK usando módulos de Go:

go get github.com/dodopayments/dodopayments-go

O para fijar a una versión específica:

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

El SDK requiere Go 1.22 o versiones posteriores, aprovechando las funciones modernas de Go para un rendimiento óptimo.

Inicio Rápido

Inicializa el cliente y crea tu primera sesión de pago:

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

Almacena siempre tus claves API de forma segura usando variables de entorno. Nunca las codifiques directamente en tu código fuente.

Características Principales

Context Support

Compatibilidad total con context.Context para cancelaciones y tiempos de espera

Strong Typing

Solicitudes y respuestas fuertemente tipadas para seguridad en tiempo de compilación

Middleware

Compatibilidad extensible con middleware para registro, métricas y lógica personalizada

Goroutine Safe

Cliente seguro para hilos diseñado para operaciones concurrentes

Configuración

Contexto y Tiempos de Espera

Aprovecha el contexto de Go para tiempos de espera y cancelación:

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

Configuración de Reintentos

Configura el comportamiento de reintento automático:

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

Operaciones Comunes

Crear una Sesión de Pago

Genera una sesión de pago:

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)

Gestionar Clientes

Crea y recupera información de clientes:

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

Manejar Suscripciones

Crea y gestiona suscripciones recurrentes:

POST /subscriptions (the SDK’s subscriptions.create method) está obsoleto. Sigue funcionando para las integraciones existentes, pero las nuevas integraciones deben crear suscripciones mediante 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 requiere como mínimo el código ISO de dos letras Country. Customer es un CustomerRequestUnionParam: pasa AttachExistingCustomerParam{CustomerID: ...} para un cliente existente o NewCustomerParam{Email: ..., Name: ...} para uno nuevo. ProductPrice se expresa en la denominación más baja de la moneda.

Facturación basada en el uso

Ingerir eventos de uso

Registra eventos personalizados:

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

Enumerar eventos de uso

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

Gestión de errores

Cuando la API devuelve un código de estado que no indica éxito, el SDK devuelve un error de tipo *dodopayments.Error. Expone StatusCode, el *http.Request subyacente y *http.Response, además del JSON del cuerpo del error. Usa el patrón errors.As para inspeccionarlo y evalúa StatusCode para gestionar casos específicos:

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

Añade middleware personalizado para el registro o las métricas:

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

Concurrencia

El cliente admite un uso simultáneo seguro:

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

Recursos

GitHub Repository

Consulta el código fuente y contribuye

API Reference

Documentación completa de la API

Discord Community

Obtén ayuda y conéctate con otros desarrolladores

Report Issues

Informa de errores o solicita funcionalidades

Soporte

¿Necesitas ayuda con el Go SDK?

Discord: Únete a nuestro servidor de la comunidad para recibir soporte en tiempo real
Correo electrónico: Contáctanos en support@dodopayments.com
GitHub: Abre un issue en el repositorio

Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta las directrices para contribuir para comenzar.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

Instalación

Inicio Rápido

Características Principales

Context Support

Strong Typing

Middleware

Goroutine Safe

Configuración

Contexto y Tiempos de Espera

Configuración de Reintentos

Operaciones Comunes

Crear una Sesión de Pago

Gestionar Clientes

Manejar Suscripciones

Facturación basada en el uso

Ingerir eventos de uso

Enumerar eventos de uso

Gestión de errores

Middleware

Concurrencia

Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

Soporte

Contribuciones

​Instalación

​Inicio Rápido

​Características Principales

Context Support

Strong Typing

Middleware

Goroutine Safe

​Configuración

​Contexto y Tiempos de Espera

​Configuración de Reintentos

​Operaciones Comunes

​Crear una Sesión de Pago

​Gestionar Clientes

​Manejar Suscripciones

​Facturación basada en el uso

​Ingerir eventos de uso

​Enumerar eventos de uso

​Gestión de errores

​Middleware

​Concurrencia

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Soporte

​Contribuciones

Instalación

Inicio Rápido

Características Principales

Configuración

Contexto y Tiempos de Espera

Configuración de Reintentos

Operaciones Comunes

Crear una Sesión de Pago

Gestionar Clientes

Manejar Suscripciones

Facturación basada en el uso

Ingerir eventos de uso

Enumerar eventos de uso

Gestión de errores

Middleware

Concurrencia

Recursos

Soporte

Contribuciones