Skip to main content
Il C# SDK offre alle applicazioni .NET accesso tipizzato alla REST API di Dodo Payments. Ogni metodo API è asincrono e restituisce un Task, le richieste e le risposte sono classi tipizzate e il client ripete automaticamente le richieste non riuscite.

Installation

Install the package from NuGet:
L’SDK richiede .NET Standard 2.0 o versioni successive e include anche una build per .NET 8. Funziona con ASP.NET Core, applicazioni console e altri tipi di progetti .NET. Gli esempi di questa pagina usano la sintassi C# 12, ad esempio le collection expressions.

Quick Start

Crea un client, quindi crea una checkout session:
Se non imposti BearerToken, il client legge la variabile d’ambiente DODO_PAYMENTS_API_KEY. Se non imposti BaseUrl o DODO_PAYMENTS_BASE_URL, il client si connette alla live mode. Per usare la test mode, consulta Environments. Una API key della test mode funziona solo nella test mode.
Conserva le API key nelle variabili d’ambiente, nei user secrets o in Azure Key Vault. Non inserirle mai direttamente nel codice sorgente e non eseguirne il commit nel version control.

Funzionalità principali

Async/Await

Ogni metodo API restituisce un Task e accetta un CancellationToken opzionale.

Strong Typing

Classi tipizzate per richieste e risposte, con annotazioni nullable reference type.

Smart Retries

Due retry per impostazione predefinita, con exponential backoff, per gli errori di connessione e gli status code ripetibili.

Error Handling

Una exception class per ogni status HTTP error comune, con lo status code e il response body.

Configurazione

Variabili d’ambiente

Memorizza la tua API key in una variabile d’ambiente:
.env
Un client creato con new() legge le proprie impostazioni dall’ambiente:
Il client legge queste variabili d’ambiente quando non imposti la proprietà corrispondente: Se non è impostato né BearerToken né DODO_PAYMENTS_API_KEY, il client genera DodoPaymentsInvalidDataException. WebhookKey contiene il webhook signing secret, ma il C# SDK non dispone di un metodo che verifichi le firme dei webhook. Per verificarle, consulta Webhooks.

Configurazione manuale

Imposta le proprietà sul client per sovrascrivere le variabili d’ambiente:

Environments

Per impostazione predefinita, il client si connette alla live mode (https://live.dodopayments.com). Per usare la test mode (https://test.dodopayments.com), imposta BaseUrl su EnvironmentUrl.TestMode:

Retry

L’SDK ripete le richieste in caso di errori di connessione e di risposte con status 408, 409, 429 o 500 e superiori. Per impostazione predefinita, esegue due retry con exponential backoff. Imposta MaxRetries per modificare il numero di retry oppure impostalo su 0 per disattivare i retry:

Timeout

Ogni tentativo di richiesta termina dopo 1 minuto per impostazione predefinita. Il timeout non include i retry. Imposta Timeout per modificarlo:

Override per singola richiesta

Per modificare le impostazioni di una singola chiamata, chiama WithOptions sul client o su un service. Restituisce una copia modificata che condivide lo stesso connection pool, mentre il client originale non cambia:

Operazioni comuni

Gli esempi di questa sezione usano il client di Quick Start.

Crea una checkout session

Crea una checkout session, quindi reindirizza il cliente all’CheckoutUrl restituito:
Ogni checkout URL funziona una sola volta e scade dopo 24 ore. Per tutte le opzioni della sessione, consulta Checkout Sessions.

Gestisci i clienti

Crea un cliente con un indirizzo email e un nome, quindi recuperalo tramite ID:
Customers.Retrieve accetta anche l’ID come stringa, ad esempio client.Customers.Retrieve("cus_123").

Gestisci le subscription

Crea una subscription, quindi addebitala se si tratta di una subscription on-demand.
POST /subscriptions (il metodo Subscriptions.Create dell’SDK) è deprecato. Continua a funzionare per le integrazioni esistenti, ma le nuove integrazioni devono creare le subscription tramite una Checkout Session.
Billing richiede solo Country, un codice paese ISO di due lettere. Customer accetta un AttachExistingCustomer per associare un cliente esistente oppure un NewCustomer per crearne uno. Charge è destinato alle subscription on-demand, mentre ProductPrice è espresso nell’unità minima della valuta.

Gestione degli errori

Quando l’API restituisce uno status di errore, l’SDK genera una sottoclasse di DodoPaymentsApiException, che dispone delle proprietà StatusCode e ResponseBody. La exception class dipende dallo status code. Tutte le eccezioni 4xx ereditano da DodoPayments4xxException. Uno status 4xx senza una classe specifica, ad esempio 409, genera DodoPayments4xxException. DodoPaymentsUnexpectedStatusCodeException gestisce gli status al di fuori degli intervalli 4xx e 5xx. L’SDK genera anche queste eccezioni:
  • DodoPaymentsIOException: un errore I/O o di rete.
  • DodoPaymentsInvalidDataException: l’SDK non ha potuto interpretare i dati della risposta, ad esempio perché manca una proprietà obbligatoria.
  • DodoPaymentsException: la classe base di ogni eccezione dell’SDK.

Paginazione

I metodi di elenco restituiscono una pagina di risultati. Puoi scorrere ogni elemento oppure spostarti manualmente tra le pagine.

Paginazione automatica

Paginate restituisce un IAsyncEnumerable che recupera la pagina successiva quando necessario:

Paginazione manuale

Per lavorare su una pagina alla volta, leggi Items, quindi chiama HasNext() e Next():
Per impostare la dimensione della pagina, passa un PaymentListParams dal namespace DodoPayments.Client.Models.Payments, ad esempio client.Payments.List(new PaymentListParams { PageSize = 50 }).

Integrazione con ASP.NET Core

Registra un client come singleton nel container di dependency injection e leggi la API key dalla configurazione:
Program.cs
Aggiungi la chiave alla configurazione, ad esempio in appsettings.json:
appsettings.json
In sviluppo, memorizza la chiave con user secrets invece che in appsettings.json:

Risorse

NuGet Package

Versioni dei package e comandi di installazione.

GitHub Repository

Codice sorgente, release ed esempi.

API Reference

Ogni endpoint, parametro e risposta.

Discord Community

Fai domande e parla con altri sviluppatori.

Supporto

Per ricevere assistenza sul C# SDK:
Ultima modifica il 26 settembre 2026