Go - Dodo Payments Documentation

O SDK Go oferece às aplicações Go acesso tipado à API REST do Dodo Payments. Cada método recebe um context.Context, os parâmetros de requisição usam um wrapper Field que separa valores zero de campos omitidos, e você pode adicionar middleware a cada requisição.

Instalação

Adicione o módulo ao seu projeto:

go get github.com/dodopayments/dodopayments-go

Para fixar uma versão específica:

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

O SDK requer Go 1.22 ou posterior.

Início Rápido

Crie um cliente e, em seguida, uma sessão de checkout:

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 você omitir option.WithBearerToken, NewClient lê a variável de ambiente DODO_PAYMENTS_API_KEY. Se você omitir option.WithEnvironmentTestMode(), o cliente se conecta ao modo live. Uma chave de API do modo de teste funciona somente no modo de teste.

Mantenha as chaves de API em variáveis de ambiente ou em um gerenciador de secrets. Nunca as inclua diretamente no código-fonte.

Recursos principais

Context Support

Cada método recebe um context.Context para cancelamento e timeouts.

Strong Typing

Parâmetros de requisição e structs de resposta tipados para verificações em tempo de compilação.

Middleware

Adicione middleware com option.WithMiddleware para logging, métricas e lógica personalizada.

Goroutine Safe

Compartilhe um cliente entre goroutines.

Configuração

NewClient lê DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY (seu secret de assinatura de webhook) e DODO_PAYMENTS_BASE_URL do ambiente. As opções que você fornece, como option.WithBearerToken, option.WithWebhookKey e option.WithBaseURL, substituem esses valores. Para verificar um webhook, passe o corpo bruto da requisição e os headers para client.Webhooks.Unwrap(rawBody, r.Header). Ele verifica a assinatura usando sua chave de webhook e retorna o evento analisado. client.Webhooks.UnsafeUnwrap(rawBody) analisa o corpo sem verificá-lo; portanto, use-o somente para testes. Consulte Webhooks. Os exemplos nesta página usam o client de Início rápido.

Context e timeouts

As requisições não têm timeout por padrão. Um deadline de context limita toda a chamada, incluindo os retries. Para limitar cada tentativa, adicione 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)
	}
}

Configuração de retries

O SDK faz retry de erros de conexão e de respostas com status 408, 409, 429 ou 500 e superiores. Por padrão, ele faz retry duas vezes, com backoff exponencial. Defina option.WithMaxRetries no cliente ou em uma única requisição:

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

Operações comuns

Os exemplos nesta seção também usam um context, por exemplo ctx := context.Background().

Criar uma sessão de checkout

Crie uma sessão de checkout e redirecione o cliente para o CheckoutURL retornado:

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)

Cada URL de checkout funciona uma vez e expira após 24 horas. Para ver todas as opções de sessão, consulte Sessões de checkout.

Gerenciar clientes

Crie um cliente com um endereço de e-mail e um nome e, em seguida, recupere-o pelo ID. Os valores de metadata usam os tipos de união do pacote 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)

Gerenciar assinaturas

Crie uma assinatura, cobre uma assinatura on-demand e leia o histórico de uso de uma assinatura.

POST /subscriptions (o método Subscriptions.New do SDK) está deprecated. Ele ainda funciona para integrações existentes, mas novas integrações devem criar assinaturas por meio de uma Sessão de checkout.

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 requer apenas Country, um código de país ISO de duas letras. Customer é um CustomerRequestUnionParam: passe AttachExistingCustomerParam{CustomerID: ...} para um cliente existente ou NewCustomerParam{Email: ..., Name: ...} para criar um. Charge é destinado a assinaturas on-demand, e ProductPrice está na menor unidade da moeda. GetUsageHistory retorna uma página de resultados; GetUsageHistoryAutoPaging itera por todas as páginas.

Cobrança baseada em uso

Ingerir eventos de uso

Envie eventos de uso para um cliente:

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)

O EventID é a chave de idempotência; portanto, atribua um valor exclusivo a cada evento. Se o mesmo EventID aparecer duas vezes em uma requisição, toda a requisição será rejeitada. Se um EventID já tiver sido ingerido, o novo evento será ignorado. Uma requisição aceita até 1.000 eventos. Timestamp usa como padrão o horário atual e é rejeitado se estiver mais de 1 hora no passado ou mais de 5 minutos no futuro.

Listar eventos de uso

Liste eventos filtrados por cliente e nome do 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 retorna uma página. Para iterar por todas as páginas, chame client.UsageEvents.ListAutoPaging(ctx, params) e faça um loop com iter.Next(), iter.Current() e iter.Err(). Outros métodos de listagem têm a mesma variante AutoPaging, e cada página tem um método GetNextPage().

Tratamento de erros

Quando a API retorna um status code de erro, o SDK retorna um erro do tipo *dodopayments.Error. Ele contém StatusCode, *http.Request e *http.Response, além do JSON do corpo do erro. Use errors.As para inspecioná-lo e use StatusCode em condições para tratar casos específicos:

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

Outros erros são retornados sem wrapper. Por exemplo, se o transporte HTTP falhar, você poderá receber um *url.Error que encapsula um *net.OpError. apiErr.DumpRequest(true) retorna a requisição serializada.

Middleware

Adicione middleware com option.WithMiddleware. Um middleware recebe cada requisição e uma função next que a envia:

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

Vários middlewares em uma única chamada option.WithMiddleware são executados da esquerda para a direita. O middleware passado para NewClient é executado antes do middleware passado para uma única requisição.

Concorrência

O cliente é seguro para uso concorrente, portanto você pode compartilhá-lo entre 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()
}

Recursos

GitHub Repository

Código-fonte, releases e a lista completa de métodos.

API Reference

Cada endpoint, parâmetro e resposta.

Discord Community

Faça perguntas e converse com outros desenvolvedores.

Report Issues

Relate bugs ou solicite recursos.

Suporte

Para obter ajuda com o SDK Go:

Discord: entre no servidor da comunidade para obter ajuda em tempo real.
E-mail: entre em contato pelo endereço support@dodopayments.com.
GitHub: abra uma issue no repositório.

Contribuição

Para contribuir, leia as diretrizes de contribuição.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Go

Instalação

Início Rápido

Recursos principais

Context Support

Strong Typing

Middleware

Goroutine Safe

Configuração

Context e timeouts

Configuração de retries

Operações comuns

Criar uma sessão de checkout

Gerenciar clientes

Gerenciar assinaturas

Cobrança baseada em uso

Ingerir eventos de uso

Listar eventos de uso

Tratamento de erros

Middleware

Concorrência

Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

Suporte

Contribuição

​Instalação

​Início Rápido

​Recursos principais

Context Support

Strong Typing

Middleware

Goroutine Safe

​Configuração

​Context e timeouts

​Configuração de retries

​Operações comuns

​Criar uma sessão de checkout

​Gerenciar clientes

​Gerenciar assinaturas

​Cobrança baseada em uso

​Ingerir eventos de uso

​Listar eventos de uso

​Tratamento de erros

​Middleware

​Concorrência

​Recursos

GitHub Repository

API Reference

Discord Community

Report Issues

​Suporte

​Contribuição

Instalação

Início Rápido

Recursos principais

Configuração

Context e timeouts

Configuração de retries

Operações comuns

Criar uma sessão de checkout

Gerenciar clientes

Gerenciar assinaturas

Cobrança baseada em uso

Ingerir eventos de uso

Listar eventos de uso

Tratamento de erros

Middleware

Concorrência

Recursos

Suporte

Contribuição