> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# C#
> Integrate Dodo Payments into your .NET applications with modern async/await support
The C# SDK provides convenient access to the Dodo Payments REST API from applications written in C#. It features an async Task-based API with strong typing, automatic retries, and comprehensive error handling.
## Installation
Install the package from [NuGet](https://www.nuget.org/packages/DodoPayments.Client):
```bash theme={null}
dotnet add package DodoPayments.Client
```
The SDK requires .NET 8.0 or later. It works with ASP.NET Core, Console applications, and other .NET project types.
## Quick Start
Initialize the client and create a checkout session:
```csharp theme={null}
using System;
using DodoPayments.Client;
using DodoPayments.Client.Models.CheckoutSessions;
// Configured using the DODO_PAYMENTS_API_KEY and DODO_PAYMENTS_BASE_URL environment variables
DodoPaymentsClient client = new();
CheckoutSessionCreateParams parameters = new()
{
ProductCart =
[
new()
{
ProductID = "product_id",
Quantity = 1,
},
],
};
var checkoutSessionResponse = await client.CheckoutSessions.Create(parameters);
Console.WriteLine(checkoutSessionResponse.SessionId);
```
Always store your API keys securely using environment variables, user secrets, or Azure Key Vault. Never hardcode them in your source code or commit them to version control.
## Core Features
Full async Task-based API for non-blocking operations
Comprehensive type safety with nullable reference types
Automatic retries with exponential backoff for transient errors
Built-in exception hierarchy for precise error management
## Configuration
### Environment Variables
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```
```csharp theme={null}
// Automatically reads from environment variables
DodoPaymentsClient client = new();
```
| 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"` |
### Manual Configuration
```csharp theme={null}
DodoPaymentsClient client = new() { BearerToken = "My Bearer Token" };
```
### Environments
Switch between live and test mode:
```csharp theme={null}
using DodoPayments.Client.Core;
DodoPaymentsClient client = new() { BaseUrl = EnvironmentUrl.TestMode };
```
### Retries
The SDK automatically retries 2 times by default with exponential backoff. It retries on connection errors and status codes 408, 409, 429, and 5xx.
```csharp theme={null}
// Custom retry count
DodoPaymentsClient client = new() { MaxRetries = 3 };
```
### Timeouts
Requests time out after 1 minute by default.
```csharp theme={null}
DodoPaymentsClient client = new() { Timeout = TimeSpan.FromSeconds(30) };
```
### Per-Request Overrides
Temporarily modify configuration for a single request using `WithOptions`:
```csharp theme={null}
var response = await client
.WithOptions(options => options with
{
Timeout = TimeSpan.FromSeconds(10),
MaxRetries = 5,
})
.CheckoutSessions.Create(parameters);
```
## Common Operations
### Create a Checkout Session
```csharp theme={null}
var parameters = new CheckoutSessionCreateParams
{
ProductCart =
[
new()
{
ProductID = "prod_123",
Quantity = 1
}
],
ReturnUrl = "https://yourdomain.com/return"
};
var session = await client.CheckoutSessions.Create(parameters);
Console.WriteLine($"Checkout URL: {session.CheckoutUrl}");
```
### Manage Customers
```csharp theme={null}
// 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("cus_123");
Console.WriteLine($"Customer: {retrieved.Name} ({retrieved.Email})");
```
### Handle Subscriptions
```csharp theme={null}
using DodoPayments.Client.Models.Payments;
using DodoPayments.Client.Models.Subscriptions;
// Create a subscription
var subscription = await client.Subscriptions.Create(new SubscriptionCreateParams
{
Billing = new BillingAddress
{
Country = "US",
City = "San Francisco",
State = "CA",
Street = "1 Market St",
Zipcode = "94105",
},
Customer = new AttachExistingCustomer { CustomerID = "cus_123" },
ProductID = "pdt_456",
Quantity = 1,
});
// Charge an on-demand subscription
// ProductPrice is in the lowest currency denomination (e.g., 2500 = $25.00 USD)
var charge = await client.Subscriptions.Charge(
subscription.SubscriptionId,
new SubscriptionChargeParams { ProductPrice = 2500 }
);
```
`Billing` requires at minimum the two-letter ISO `Country` code. Use `AttachExistingCustomer` to attach an existing customer, or `NewCustomer` to create one. `ProductPrice` is in the lowest currency denomination.
## Error Handling
The SDK throws specific exceptions based on the HTTP status code. All 4xx errors inherit from `DodoPayments4xxException`.
| Status | Exception |
| ------ | ------------------------------------------- |
| 400 | `DodoPaymentsBadRequestException` |
| 401 | `DodoPaymentsUnauthorizedException` |
| 403 | `DodoPaymentsForbiddenException` |
| 404 | `DodoPaymentsNotFoundException` |
| 422 | `DodoPaymentsUnprocessableEntityException` |
| 429 | `DodoPaymentsRateLimitException` |
| 5xx | `DodoPayments5xxException` |
| others | `DodoPaymentsUnexpectedStatusCodeException` |
Other exception types:
* `DodoPaymentsIOException`: I/O networking errors
* `DodoPaymentsInvalidDataException`: Failure to interpret parsed data
* `DodoPaymentsException`: Base class for all exceptions
## Pagination
### Auto-Pagination
Iterate through all results across all pages using the `Paginate` method, which returns an `IAsyncEnumerable`:
```csharp theme={null}
var page = await client.Payments.List(parameters);
await foreach (var item in page.Paginate())
{
Console.WriteLine(item);
}
```
### Manual Pagination
```csharp theme={null}
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();
}
```
## ASP.NET Core Integration
Register the client in your DI container:
```csharp Program.cs theme={null}
using DodoPayments.Client;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton(sp =>
{
var configuration = sp.GetRequiredService();
return new DodoPaymentsClient
{
BearerToken = configuration["DodoPayments:ApiKey"]
};
});
var app = builder.Build();
app.Run();
```
```json appsettings.json theme={null}
{
"DodoPayments": {
"ApiKey": "your_api_key_here"
}
}
```
For development, use [user secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) instead of storing keys in `appsettings.json`:
```bash theme={null}
dotnet user-secrets init
dotnet user-secrets set "DodoPayments:ApiKey" "your_api_key_here"
```
## Resources
View package on NuGet Gallery
View source code and contribute
Complete API documentation
Get help and connect with developers
## Support
Need help with the C# SDK?
* **Discord**: Join our [community server](https://discord.gg/bYqAp4ayYh) for real-time support
* **Email**: Contact us at [support@dodopayments.com](mailto:support@dodopayments.com)
* **GitHub**: Open an issue on the [repository](https://github.com/dodopayments/dodopayments-csharp)