C# - Dodo Payments Documentation

The C# SDK gives .NET applications typed access to the Dodo Payments REST API. Every API method is asynchronous and returns a Task, requests and responses are typed classes, and the client retries failed requests for you.

Installation

Install the package from NuGet:

dotnet add package DodoPayments.Client

The SDK requires .NET Standard 2.0 or later, and it also ships a .NET 8 build. It works with ASP.NET Core, console applications, and other .NET project types. The examples on this page use C# 12 syntax, such as collection expressions.

Quick Start

Create a client, then create a checkout session:

using System;
using DodoPayments.Client;
using DodoPayments.Client.Models.CheckoutSessions;

// Configured using the DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_WEBHOOK_KEY, and DODO_PAYMENTS_BASE_URL environment variables
DodoPaymentsClient client = new();

CheckoutSessionCreateParams parameters = new()
{
    ProductCart =
    [
        new()
        {
            ProductID = "pdt_123",
            Quantity = 1,
        },
    ],
};

var checkoutSessionResponse = await client.CheckoutSessions.Create(parameters);

Console.WriteLine(checkoutSessionResponse.SessionID);

If you don’t set BearerToken, the client reads the DODO_PAYMENTS_API_KEY environment variable. If you don’t set BaseUrl or DODO_PAYMENTS_BASE_URL, the client connects to live mode. To use test mode, see Environments. A test mode API key works only in test mode.

Keep API keys in environment variables, user secrets, or Azure Key Vault. Never hardcode them in your source code or commit them to version control.

Core Features

Async/Await

Every API method returns a Task and accepts an optional CancellationToken.

Strong Typing

Typed request and response classes, with nullable reference type annotations.

Smart Retries

Two retries by default, with exponential backoff, for connection errors and retryable status codes.

Error Handling

An exception class for each common HTTP error status, with the status code and response body.

Configuration

Environment Variables

Store your API key in an environment variable:

.env

DODO_PAYMENTS_API_KEY=dodo_test_...

A client created with new() reads its settings from the environment:

// Automatically reads from environment variables
DodoPaymentsClient client = new();

The client reads these environment variables when you don’t set the matching property:

Property	Environment variable	Required	Default value
`BearerToken`	`DODO_PAYMENTS_API_KEY`	true	-
`WebhookKey`	`DODO_PAYMENTS_WEBHOOK_KEY`	false	-
`BaseUrl`	`DODO_PAYMENTS_BASE_URL`	true	`"https://live.dodopayments.com"`

If neither BearerToken nor DODO_PAYMENTS_API_KEY is set, the client throws DodoPaymentsInvalidDataException. WebhookKey holds your webhook signing secret, but the C# SDK has no method that verifies webhook signatures. To verify them, follow Webhooks.

Manual Configuration

Set properties on the client to override the environment variables:

DodoPaymentsClient client = new() { BearerToken = "dodo_test_..." };

Environments

The client connects to live mode (https://live.dodopayments.com) by default. To use test mode (https://test.dodopayments.com), set BaseUrl to EnvironmentUrl.TestMode:

using DodoPayments.Client.Core;

DodoPaymentsClient client = new() { BaseUrl = EnvironmentUrl.TestMode };

Retries

The SDK retries connection errors and responses with status 408, 409, 429, or 500 and above. It retries twice by default, with exponential backoff. Set MaxRetries to change the number of retries, or set it to 0 to turn retries off:

// Custom retry count
DodoPaymentsClient client = new() { MaxRetries = 3 };

Timeouts

Each request attempt times out after 1 minute by default. The timeout doesn’t include retries. Set Timeout to change it:

DodoPaymentsClient client = new() { Timeout = TimeSpan.FromSeconds(30) };

Per-Request Overrides

To change settings for a single call, call WithOptions on the client or on a service. It returns a modified copy that shares the same connection pool, and the original client doesn’t change:

var response = await client
    .WithOptions(options => options with
    {
        Timeout = TimeSpan.FromSeconds(10),
        MaxRetries = 5,
    })
    .CheckoutSessions.Create(parameters);

Workload Identity

The SDK can use workload identity federation instead of an API key. The SDK exchanges an OIDC token from your CI or cloud platform for a short-lived Dodo Payments token. It refreshes the token before the token expires. This feature is available from version 6.42.0. Before you start, create an identity provider and a mapping in the dashboard. Refer to Dashboard Setup. This example uses the GitHub Actions helper, WorkloadIdentityProviders.GitHubActions():

using DodoPayments.Client;
using DodoPayments.Client.Core;

DodoPaymentsClient client = new()
{
    BaseUrl = EnvironmentUrl.LiveMode,
    WorkloadIdentity = new()
    {
        IdentityProviderID = "wip_...",
        Provider = WorkloadIdentityProviders.GitHubActions(),
    },
};

If DODO_PAYMENTS_API_KEY is not set and DODO_PAYMENTS_IDENTITY_PROVIDER_ID is set, the SDK uses workload identity. It finds the platform from the environment. To stop the token before it expires, for example at the end of a CI job, revoke it:

await client.RevokeWorkloadIdentityToken();

Do not set an API key and workload identity together. The SDK gives an error when you set the two options.

For the other platform helpers and the refresh behavior, refer to Use Workload Identity with the SDKs.

Common Operations

The examples in this section use the client from Quick Start.

Create a Checkout Session

Create a checkout session, then redirect the customer to the returned CheckoutUrl:

var parameters = new CheckoutSessionCreateParams
{
    ProductCart =
    [
        new()
        {
            ProductID = "pdt_123",
            Quantity = 1
        }
    ],
    ReturnUrl = "https://yourdomain.com/return"
};

var session = await client.CheckoutSessions.Create(parameters);
Console.WriteLine($"Checkout URL: {session.CheckoutUrl}");

Each checkout URL works once and expires after 24 hours. For every session option, see Checkout Sessions.

Manage Customers

Create a customer with an email address and name, then retrieve it by ID:

using DodoPayments.Client.Models.Customers;

// Create a customer
var customer = await client.Customers.Create(new CustomerCreateParams
{
    Email = "customer@example.com",
    Name = "John Doe"
});

// Retrieve customer
var retrieved = await client.Customers.Retrieve(new CustomerRetrieveParams { CustomerID = "cus_123" });
Console.WriteLine($"Customer: {retrieved.Name} ({retrieved.Email})");

Customers.Retrieve also accepts the ID as a string, for example client.Customers.Retrieve("cus_123").

Handle Subscriptions

Start a subscription with a checkout session, then charge it if it’s an on-demand subscription.

using DodoPayments.Client.Models.CheckoutSessions;
using DodoPayments.Client.Models.Payments;
using DodoPayments.Client.Models.Subscriptions;

// Start a subscription: put a subscription product in ProductCart
var session = await client.CheckoutSessions.Create(new CheckoutSessionCreateParams
{
    ProductCart =
    [
        new()
        {
            ProductID = "pdt_456",
            Quantity = 1,
        },
    ],
    Customer = new AttachExistingCustomer { CustomerID = "cus_123" },
    ReturnUrl = "https://yourdomain.com/return",
});
Console.WriteLine($"Checkout URL: {session.CheckoutUrl}");

// Charge an on-demand subscription
// ProductPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
var charge = await client.Subscriptions.Charge(new SubscriptionChargeParams
{
    SubscriptionID = "sub_123",
    ProductPrice = 2500,
});

The subscription starts when the customer completes checkout. Read its subscription_id from the subscription.active webhook or from the return_url query parameters. Customer takes an AttachExistingCustomer to attach an existing customer or a NewCustomer to create one. Charge is for on-demand subscriptions, and ProductPrice is in the smallest currency unit.

Error Handling

When the API returns an error status, the SDK throws a subclass of DodoPaymentsApiException, which has StatusCode and ResponseBody properties. The exception class depends on the status code. All 4xx exceptions inherit from DodoPayments4xxException.

Status	Exception
400	`DodoPaymentsBadRequestException`
401	`DodoPaymentsUnauthorizedException`
403	`DodoPaymentsForbiddenException`
404	`DodoPaymentsNotFoundException`
422	`DodoPaymentsUnprocessableEntityException`
429	`DodoPaymentsRateLimitException`
5xx	`DodoPayments5xxException`
others	`DodoPaymentsUnexpectedStatusCodeException`

A 4xx status without its own class, such as 409, throws DodoPayments4xxException. DodoPaymentsUnexpectedStatusCodeException covers statuses outside the 4xx and 5xx ranges. The SDK also throws these exceptions:

DodoPaymentsIOException: An I/O or network error.
DodoPaymentsInvalidDataException: The SDK couldn’t interpret the response data, for example because a required property is missing.
DodoPaymentsException: The base class of every SDK exception.

Pagination

List methods return one page of results. You can iterate over every item or move through the pages yourself.

Auto-Pagination

Paginate returns an IAsyncEnumerable that fetches the next page when it needs it:

var page = await client.Payments.List();
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}

Manual Pagination

To work with one page at a time, read Items, then call HasNext() and Next():

var page = await client.Payments.List();
while (true)
{
    foreach (var item in page.Items)
    {
        Console.WriteLine(item);
    }
    if (!page.HasNext())
    {
        break;
    }
    page = await page.Next();
}

To set the page size, pass a PaymentListParams from the DodoPayments.Client.Models.Payments namespace, for example client.Payments.List(new PaymentListParams { PageSize = 50 }).

ASP.NET Core Integration

Program.cs

using DodoPayments.Client;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<DodoPaymentsClient>(sp =>
{
    var configuration = sp.GetRequiredService<IConfiguration>();
    return new DodoPaymentsClient
    {
        BearerToken = configuration["DodoPayments:ApiKey"]
    };
});

var app = builder.Build();
app.Run();

Add the key to your configuration, for example in appsettings.json:

appsettings.json

{
  "DodoPayments": {
    "ApiKey": "dodo_test_..."
  }
}

In development, store the key with user secrets instead of in appsettings.json:

dotnet user-secrets init
dotnet user-secrets set "DodoPayments:ApiKey" "dodo_test_..."

Resources

NuGet Package

Package versions and install commands.

GitHub Repository

Source code, releases, and examples.

API Reference

Every endpoint, parameter, and response.

Discord Community

Ask questions and talk with other developers.

Support

For help with the C# SDK:

Discord: Join the community server for real-time help.
Email: Contact support@dodopayments.com.
GitHub: Open an issue on the repository.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

C#

Installation

Quick Start

Core Features

Async/Await

Strong Typing

Smart Retries

Error Handling

Configuration

Environment Variables

Manual Configuration

Environments

Retries

Timeouts

Per-Request Overrides

Workload Identity

Common Operations

Create a Checkout Session

Manage Customers

Handle Subscriptions

Error Handling

ASP.NET Core Integration

Resources

NuGet Package

GitHub Repository

API Reference

Discord Community

Support

​Installation

​Quick Start

​Core Features

Async/Await

Strong Typing

Smart Retries

Error Handling

​Configuration

​Environment Variables

​Manual Configuration

​Environments

​Retries

​Timeouts

​Per-Request Overrides

​Workload Identity

​Common Operations

​Create a Checkout Session

​Manage Customers

​Handle Subscriptions

​Error Handling

​Pagination

​Auto-Pagination

​Manual Pagination

​ASP.NET Core Integration

​Resources

NuGet Package

GitHub Repository

API Reference

Discord Community

​Support

Installation

Quick Start

Core Features

Configuration

Environment Variables

Manual Configuration

Environments

Retries

Timeouts

Per-Request Overrides

Workload Identity

Common Operations

Create a Checkout Session

Manage Customers

Handle Subscriptions

Error Handling

Pagination

Auto-Pagination

Manual Pagination

ASP.NET Core Integration

Resources

Support