> ## 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#
> Usa el SDK de C# de Dodo Payments para crear sesiones de checkout, clientes y suscripciones desde .NET, con modelos tipados, reintentos automáticos y paginación.
El SDK de C# proporciona a las aplicaciones .NET acceso tipado a la API REST de Dodo Payments. Cada método de la API es asíncrono y devuelve un `Task`, las solicitudes y respuestas son clases tipadas, y el cliente reintenta las solicitudes fallidas por ti.
## Instalación
Instala el paquete desde [NuGet](https://www.nuget.org/packages/DodoPayments.Client):
```bash theme={null}
dotnet add package DodoPayments.Client
```
El SDK requiere .NET Standard 2.0 o posterior, y también incluye una compilación para .NET 8. Funciona con ASP.NET Core, aplicaciones de consola y otros tipos de proyectos .NET. Los ejemplos de esta página usan la sintaxis de C# 12, como las expresiones de colección.
## Inicio Rápido
Crea un cliente y, después, crea una sesión de checkout:
```csharp theme={null}
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);
```
Si no estableces `BearerToken`, el cliente lee la variable de entorno `DODO_PAYMENTS_API_KEY`. Si no estableces `BaseUrl` ni `DODO_PAYMENTS_BASE_URL`, el cliente se conecta al modo live. Para usar el modo test, consulta [Entornos](#environments). Una clave de API del modo test solo funciona en el modo test.
Guarda las claves de API en variables de entorno, secretos de usuario o Azure Key Vault. Nunca las incluyas directamente en el código fuente ni las confirmes en el control de versiones.
## Funciones principales
Cada método de la API devuelve un `Task` y acepta un `CancellationToken` opcional.
Clases tipadas para solicitudes y respuestas, con anotaciones de tipos de referencia anulables.
Dos reintentos de forma predeterminada, con retroceso exponencial, para errores de conexión y códigos de estado que permiten reintentos.
Una clase de excepción para cada error HTTP habitual, con el código de estado y el cuerpo de la respuesta.
## Configuración
### Variables de entorno
Guarda tu clave de API en una variable de entorno:
```bash .env theme={null}
DODO_PAYMENTS_API_KEY=your_api_key_here
```
Un cliente creado con `new()` lee su configuración del entorno:
```csharp theme={null}
// Automatically reads from environment variables
DodoPaymentsClient client = new();
```
El cliente lee estas variables de entorno cuando no estableces la propiedad correspondiente:
| Propiedad | Variable de entorno | Obligatoria | Valor predeterminado |
| - | - | - | - |
| `BearerToken` | `DODO_PAYMENTS_API_KEY` | true | - |
| `WebhookKey` | `DODO_PAYMENTS_WEBHOOK_KEY` | false | - |
| `BaseUrl` | `DODO_PAYMENTS_BASE_URL` | true | `"https://live.dodopayments.com"` |
Si no se establece `BearerToken` ni `DODO_PAYMENTS_API_KEY`, el cliente lanza `DodoPaymentsInvalidDataException`. `WebhookKey` contiene tu secreto de firma de webhook, pero el SDK de C# no tiene ningún método que verifique las firmas de webhook. Para verificarlas, sigue la guía de [Webhooks](/developer-resources/webhooks).
### Configuración manual
Establece propiedades en el cliente para sobrescribir las variables de entorno:
```csharp theme={null}
DodoPaymentsClient client = new() { BearerToken = "My Bearer Token" };
```
### Entornos
De forma predeterminada, el cliente se conecta al modo live (`https://live.dodopayments.com`). Para usar el modo test (`https://test.dodopayments.com`), establece `BaseUrl` en `EnvironmentUrl.TestMode`:
```csharp theme={null}
using DodoPayments.Client.Core;
DodoPaymentsClient client = new() { BaseUrl = EnvironmentUrl.TestMode };
```
### Reintentos
El SDK reintenta los errores de conexión y las respuestas con los estados 408, 409, 429 o 500 y superiores. De forma predeterminada, realiza dos reintentos con retroceso exponencial. Establece `MaxRetries` para cambiar el número de reintentos o establécelo en `0` para desactivar los reintentos:
```csharp theme={null}
// Custom retry count
DodoPaymentsClient client = new() { MaxRetries = 3 };
```
### Tiempos de espera
Cada intento de solicitud agota el tiempo de espera después de 1 minuto de forma predeterminada. El tiempo de espera no incluye los reintentos. Establece `Timeout` para cambiarlo:
```csharp theme={null}
DodoPaymentsClient client = new() { Timeout = TimeSpan.FromSeconds(30) };
```
### Sobrescrituras por solicitud
Para cambiar la configuración de una sola llamada, llama a `WithOptions` en el cliente o en un servicio. Devuelve una copia modificada que comparte el mismo grupo de conexiones, y el cliente original no cambia:
```csharp theme={null}
var response = await client
.WithOptions(options => options with
{
Timeout = TimeSpan.FromSeconds(10),
MaxRetries = 5,
})
.CheckoutSessions.Create(parameters);
```
## Operaciones habituales
Los ejemplos de esta sección usan el `client` de [Inicio rápido](#quick-start).
### Crear una sesión de checkout
Crea una sesión de checkout y, después, redirige al cliente al `CheckoutUrl` devuelto:
```csharp theme={null}
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}");
```
Cada URL de checkout funciona una vez y caduca después de 24 horas. Para consultar todas las opciones de sesión, consulta [Sesiones de checkout](/developer-resources/checkout-session).
### Gestionar clientes
Crea un cliente con una dirección de correo electrónico y un nombre y, después, recupéralo por su ID:
```csharp theme={null}
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` también acepta el ID como cadena, por ejemplo `client.Customers.Retrieve("cus_123")`.
### Gestionar suscripciones
Crea una suscripción y, después, cárgala si es una suscripción bajo demanda.
`POST /subscriptions` (el método `Subscriptions.Create` del SDK) está **obsoleto**. Sigue funcionando para integraciones existentes, pero las nuevas integraciones deben crear suscripciones mediante una [sesión de checkout](/developer-resources/checkout-session).
```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(new SubscriptionChargeParams
{
SubscriptionID = subscription.SubscriptionID,
ProductPrice = 2500,
});
```
`Billing` solo requiere `Country`, un código de país ISO de dos letras. `Customer` acepta un `AttachExistingCustomer` para asociar un cliente existente o un `NewCustomer` para crear uno. `Charge` es para [suscripciones bajo demanda](/developer-resources/ondemand-subscriptions), y `ProductPrice` está expresado en la unidad monetaria más pequeña.
## Gestión de errores
Cuando la API devuelve un estado de error, el SDK lanza una subclase de `DodoPaymentsApiException`, que tiene las propiedades `StatusCode` y `ResponseBody`. La clase de excepción depende del código de estado. Todas las excepciones 4xx heredan de `DodoPayments4xxException`.
| Estado | Excepción |
| - | - |
| 400 | `DodoPaymentsBadRequestException` |
| 401 | `DodoPaymentsUnauthorizedException` |
| 403 | `DodoPaymentsForbiddenException` |
| 404 | `DodoPaymentsNotFoundException` |
| 422 | `DodoPaymentsUnprocessableEntityException` |
| 429 | `DodoPaymentsRateLimitException` |
| 5xx | `DodoPayments5xxException` |
| otros | `DodoPaymentsUnexpectedStatusCodeException` |
Un estado 4xx sin una clase propia, como 409, lanza `DodoPayments4xxException`. `DodoPaymentsUnexpectedStatusCodeException` cubre los estados fuera de los rangos 4xx y 5xx.
El SDK también lanza estas excepciones:
* `DodoPaymentsIOException`: Un error de E/S o de red.
* `DodoPaymentsInvalidDataException`: El SDK no pudo interpretar los datos de respuesta, por ejemplo, porque falta una propiedad obligatoria.
* `DodoPaymentsException`: La clase base de todas las excepciones del SDK.
## Paginación
Los métodos de listado devuelven una página de resultados. Puedes iterar sobre cada elemento o avanzar por las páginas manualmente.
### Paginación automática
`Paginate` devuelve un `IAsyncEnumerable` que obtiene la página siguiente cuando la necesita:
```csharp theme={null}
var page = await client.Payments.List();
await foreach (var item in page.Paginate())
{
Console.WriteLine(item);
}
```
### Paginación manual
Para trabajar con una página a la vez, lee `Items` y, después, llama a `HasNext()` y `Next()`:
```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();
}
```
Para establecer el tamaño de página, pasa un `PaymentListParams` del espacio de nombres `DodoPayments.Client.Models.Payments`, por ejemplo `client.Payments.List(new PaymentListParams { PageSize = 50 })`.
## Integración con ASP.NET Core
Registra un cliente como singleton en el contenedor de inyección de dependencias y lee la clave de API desde la configuración:
```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();
```
Añade la clave a tu configuración, por ejemplo en `appsettings.json`:
```json appsettings.json theme={null}
{
"DodoPayments": {
"ApiKey": "your_api_key_here"
}
}
```
En desarrollo, guarda la clave con [secretos de usuario](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) en lugar de hacerlo en `appsettings.json`:
```bash theme={null}
dotnet user-secrets init
dotnet user-secrets set "DodoPayments:ApiKey" "your_api_key_here"
```
## Recursos
Versiones del paquete y comandos de instalación.
Código fuente, versiones y ejemplos.
Cada endpoint, parámetro y respuesta.
Haz preguntas y conversa con otros desarrolladores.
## Soporte
Para obtener ayuda con el SDK de C#:
* **Discord**: Únete al [servidor de la comunidad](https://discord.gg/bYqAp4ayYh) para recibir ayuda en tiempo real.
* **Correo electrónico**: Contacta con [support@dodopayments.com](mailto:support@dodopayments.com).
* **GitHub**: Abre un issue en el [repositorio](https://github.com/dodopayments/dodopayments-csharp).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.