Skip to main content
O SDK C# oferece às aplicações .NET acesso tipado à API REST do Dodo Payments. Cada método da API é assíncrono e retorna um Task, as solicitações e respostas são classes tipadas, e o cliente repete automaticamente as solicitações com falha.

Instalação

Instale o pacote do NuGet:
O SDK requer .NET Standard 2.0 ou posterior e também inclui uma compilação para .NET 8. Ele funciona com ASP.NET Core, aplicações de console e outros tipos de projetos .NET. Os exemplos nesta página usam a sintaxe do C# 12, como expressões de coleção.

Início Rápido

Crie um cliente e, em seguida, crie uma sessão de checkout:
Se você não definir BearerToken, o cliente lerá a variável de ambiente DODO_PAYMENTS_API_KEY. Se você não definir BaseUrl ou DODO_PAYMENTS_BASE_URL, o cliente se conectará ao modo live. Para usar o modo de teste, consulte Ambientes. Uma chave de API do modo de teste funciona somente no modo de teste.
Mantenha as chaves de API em variáveis de ambiente, segredos do usuário ou no Azure Key Vault. Nunca as inclua diretamente no código-fonte nem as confirme no controle de versão.

Recursos principais

Async/Await

Cada método da API retorna um Task e aceita um CancellationToken opcional.

Strong Typing

Classes tipadas de solicitação e resposta, com anotações de tipos de referência anuláveis.

Smart Retries

Duas novas tentativas por padrão, com espera exponencial, para erros de conexão e códigos de status que permitem novas tentativas.

Error Handling

Uma classe de exceção para cada status de erro HTTP comum, com o código de status e o corpo da resposta.

Configuração

Variáveis de ambiente

Armazene sua chave de API em uma variável de ambiente:
.env
Um cliente criado com new() lê suas configurações do ambiente:
O cliente lê estas variáveis de ambiente quando você não define a propriedade correspondente: Se nem BearerToken nem DODO_PAYMENTS_API_KEY estiver definido, o cliente lançará DodoPaymentsInvalidDataException. WebhookKey armazena seu segredo de assinatura de webhook, mas o SDK C# não tem um método que verifique assinaturas de webhook. Para verificá-las, siga Webhooks.

Configuração manual

Defina propriedades no cliente para substituir as variáveis de ambiente:

Ambientes

Por padrão, o cliente se conecta ao modo live (https://live.dodopayments.com). Para usar o modo de teste (https://test.dodopayments.com), defina BaseUrl como EnvironmentUrl.TestMode:

Novas tentativas

O SDK repete solicitações em caso de erros de conexão e respostas com status 408, 409, 429 ou 500 e superiores. Por padrão, ele faz duas novas tentativas, com espera exponencial. Defina MaxRetries para alterar o número de novas tentativas ou defina-o como 0 para desativá-las:

Timeouts

Cada tentativa de solicitação expira após 1 minuto por padrão. O timeout não inclui novas tentativas. Defina Timeout para alterá-lo:

Substituições por solicitação

Para alterar as configurações de uma única chamada, chame WithOptions no cliente ou em um serviço. Ele retorna uma cópia modificada que compartilha o mesmo pool de conexões, e o cliente original não é alterado:

Operações comuns

Os exemplos nesta seção usam o client de Início rápido.

Criar uma sessão de checkout

Crie uma sessão de checkout e redirecione o cliente para o CheckoutUrl retornado:
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:
Customers.Retrieve também aceita o ID como uma string, por exemplo client.Customers.Retrieve("cus_123").

Gerenciar assinaturas

Crie uma assinatura e, em seguida, cobre-a se for uma assinatura sob demanda.
POST /subscriptions (o método Subscriptions.Create do SDK) está obsoleto. Ele ainda funciona para integrações existentes, mas as novas integrações devem criar assinaturas por meio de uma Sessão de checkout.
Billing requer apenas Country, um código de país ISO de duas letras. Customer recebe um AttachExistingCustomer para associar um cliente existente ou um NewCustomer para criar um. Charge é usado para assinaturas sob demanda, e ProductPrice está na menor unidade da moeda.

Tratamento de erros

Quando a API retorna um status de erro, o SDK lança uma subclasse de DodoPaymentsApiException, que possui as propriedades StatusCode e ResponseBody. A classe de exceção depende do código de status. Todas as exceções 4xx herdam de DodoPayments4xxException. Um status 4xx sem uma classe própria, como 409, lança DodoPayments4xxException. DodoPaymentsUnexpectedStatusCodeException abrange status fora dos intervalos 4xx e 5xx. O SDK também lança estas exceções:
  • DodoPaymentsIOException: Um erro de E/S ou de rede.
  • DodoPaymentsInvalidDataException: O SDK não conseguiu interpretar os dados da resposta, por exemplo, porque uma propriedade obrigatória está ausente.
  • DodoPaymentsException: A classe base de todas as exceções do SDK.

Paginação

Os métodos de listagem retornam uma página de resultados. Você pode iterar por cada item ou percorrer as páginas manualmente.

Paginação automática

Paginate retorna um IAsyncEnumerable que busca a próxima página quando necessário:

Paginação manual

Para trabalhar com uma página por vez, leia Items e, em seguida, chame HasNext() e Next():
Para definir o tamanho da página, passe um PaymentListParams do namespace DodoPayments.Client.Models.Payments, por exemplo, client.Payments.List(new PaymentListParams { PageSize = 50 }).

Integração com ASP.NET Core

Registre um cliente como singleton no contêiner de injeção de dependências e leia a chave de API da configuração:
Program.cs
Adicione a chave à sua configuração, por exemplo, em appsettings.json:
appsettings.json
No desenvolvimento, armazene a chave usando segredos do usuário em vez de armazená-la em appsettings.json:

Recursos

NuGet Package

Versões do pacote e comandos de instalação.

GitHub Repository

Código-fonte, versões e exemplos.

API Reference

Cada endpoint, parâmetro e resposta.

Discord Community

Faça perguntas e converse com outros desenvolvedores.

Suporte

Para obter ajuda com o SDK C#:
Última modificação em 26 de setembro de 2026