The official Stripe .NET library, supporting .NET Standard 2.0+, .NET Core 2.0+, and .NET Framework 4.6.1+.
Using the .NET Core command-line interface (CLI) tools:
dotnet add package Stripe.net
Using the NuGet Command Line Interface (CLI):
nuget install Stripe.net
Using the Package Manager Console:
Install-Package Stripe.net
From within Visual Studio:
- Open the Solution Explorer.
- Right-click on a project within your solution.
- Click on Manage NuGet Packages...
- Click on the Browse tab and search for "Stripe.net".
- Click on the Stripe.net package, select the appropriate version in the right-tab and click Install.
For a comprehensive list of examples, check out the API documentation. See video demonstrations covering how to use the library.
Stripe authenticates API requests using your account’s secret key, which you can find in the Stripe Dashboard. By default, secret keys can be used to perform any API request without restriction.
Use StripeConfiguration.ApiKey
property to set the secret key.
StripeConfiguration.ApiKey = "sk_test_...";
The Create
method of the service class can be used to create a new resource:
var options = new CustomerCreateOptions
{
Email = "customer@example.com"
};
var service = new CustomerService();
Customer customer = service.Create(options);
// Newly created customer is returned
Console.WriteLine(customer.Email);
The Retrieve
method of the service class can be used to retrieve a resource:
var service = new CustomerService();
Customer customer = service.Get("cus_1234");
Console.WriteLine(customer.Email);
The Update
method of the service class can be used to update a resource:
var options = new CustomerUpdateOptions
{
Email = "updated-email@example.com"
};
var service = new CustomerService();
Customer customer = service.Update("cus_123", options);
// The updated customer is returned
Console.WriteLine(customer.Email);
The Delete
method of the service class can be used to delete a resource:
var service = new CustomerService();
Customer customer = service.Delete("cus_123", options);
The List
method on the service class can be used to list resources page-by-page.
NOTE The
List
method returns only a single page, you have to manually continue the iteration using theStartingAfter
parameter.
var service = new CustomerService();
var customers = service.List();
string lastId = null;
// Enumerate the first page of the list
foreach (Customer customer in customers)
{
lastId = customer.Id;
Console.WriteLine(customer.Email);
}
customers = service.List(new CustomerListOptions()
{
StartingAfter = lastId,
});
// Enumerate the subsequent page
foreach (Customer customer in customers)
{
lastId = customer.Id;
Console.WriteLine(customer.Email);
}
The ListAutoPaging
method on the service class can be used to automatically iterate over all pages.
var service = new CustomerService();
var customers = service.ListAutoPaging();
// Enumerate all pages of the list
foreach (Customer customer in customers)
{
Console.WriteLine(customer.Email);
}
All of the service methods accept an optional RequestOptions
object. This is
used if you want to set an idempotency key, if you are
using Stripe Connect, or if you want to pass the secret API
key on each method.
var requestOptions = new RequestOptions();
requestOptions.ApiKey = "SECRET API KEY";
requestOptions.IdempotencyKey = "SOME STRING";
requestOptions.StripeAccount = "CONNECTED ACCOUNT ID";
You can configure the library with your own custom HttpClient
:
StripeConfiguration.StripeClient = new StripeClient(
apiKey,
httpClient: new SystemNetHttpClient(httpClient));
Please refer to the Advanced client usage wiki page to see more examples of using custom clients, e.g. for using a proxy server, a custom message handler, etc.
The library automatically retries requests on intermittent failures like on a
connection error, timeout, or on certain API responses like a status 409 Conflict
. Idempotency keys are always added to requests to
make any such subsequent retries safe.
By default, it will perform up to two retries. That number can be configured
with StripeConfiguration.MaxNetworkRetries
:
StripeConfiguration.MaxNetworkRetries = 0; // Zero retries
stripe-dotnet is a typed library and it supports all public properties or parameters.
Stripe sometimes has beta features which introduce new properties or parameters that are not immediately public. The library does not support these properties or parameters until they are public but there is still an approach that allows you to use them.
To pass undocumented parameters to Stripe using stripe-dotnet you need to use the AddExtraParam()
method, as shown below:
var options = new CustomerCreateOptions
{
Email = "jenny.rosen@example.com"
}
options.AddExtraParam("secret_feature_enabled", "true");
options.AddExtraParam("secret_parameter[primary]", "primary value");
options.AddExtraParam("secret_parameter[secondary]", "secondary value");
var service = new CustomerService();
var customer = service.Create(options);
To retrieve undocumented properties from Stripe using C# you can use an option in the library to return the raw JSON object and return the property. An example of this is shown below:
var service = new CustomerService();
var customer = service.Get("cus_1234");
customer.RawJObject["secret_feature_enabled"];
customer.RawJObject["secret_parameter"]["primary"];
customer.RawJObject["secret_parameter"]["secondary"];
If you're writing a plugin that uses the library, we'd appreciate it if you
identified using StripeConfiguration.AppInfo
:
StripeConfiguration.AppInfo = new AppInfo
{
Name = "MyAwesomePlugin",
Url = "https://myawesomeplugin.info",
Version = "1.2.34",
};
This information is passed along when the library makes calls to the Stripe
API. Note that while Name
is always required, Url
and Version
are
optional.
By default, the library sends telemetry to Stripe regarding request latency and feature usage. These numbers help Stripe improve the overall latency of its API for all users, and improve popular features.
You can disable this behavior if you prefer:
StripeConfiguration.EnableTelemetry = false;
Stripe has features in the beta phase that can be accessed via the beta version of this package.
We would love for you to try these and share feedback with us before these features reach the stable phase.
To install a beta version of Stripe.net use the version parameter with dotnet add package
command:
dotnet add package Stripe.net --version <beta version>
Beta versions are appended with -beta.X
such as 45.0.0-beta.1
. Make sure to choose the version that includes support for the beta you are interested in!
Note There can be breaking changes between beta versions. Therefore we recommend pinning the package version to a specific beta version in your project file. This way you can install the same version each time without breaking changes unless you are intentionally looking for the latest beta version.
We highly recommend keeping an eye on when the beta feature you are interested in goes from beta to stable so that you can move from using a beta version of the SDK to the stable version.
If your beta feature requires a Stripe-Version
header to be sent, set the StripeConfiguration.ApiVersion
property with the StripeConfiguration.AddBetaVersion
function:
Note The
ApiVersion
can only be set in beta versions of the library.
StripeConfiguration.AddBetaVersion("feature_beta", "v3");
If you would like to send a request to an undocumented API (for example you are in a private beta), or if you prefer to bypass the method definitions in the library and specify your request details directly, you can use the RawRequestAsync
method on StripeClient
.
StripeClient client = new StripeClient();
StripeResponse response = await client.RawRequestAsync(HttpMethod.Get, "/v1/accounts/acc_123");
// Optionally use Deserialize to convert the response to strongly-typed object.
Account account = client.Deserialize<Account>(response.Content)
New features and bug fixes are released on the latest major version of the Stripe .NET client library. If you are on an older major version, we recommend that you upgrade to the latest in order to use the new features and bug fixes including those for security vulnerabilities. Older major versions of the package will continue to be available for use, but will not be receiving any updates.
.NET 8 is required to build and test Stripe.net SDK, you can install it from get.dot.net.
The test suite depends on stripe-mock, so make sure to fetch and run it from a background terminal (stripe-mock's README also contains instructions for installing via Homebrew and other methods):
go install github.com/stripe/stripe-mock@latest
stripe-mock
Run all tests from the src/StripeTests
directory:
dotnet test src
Run some tests, filtering by name:
dotnet test src --filter FullyQualifiedName~InvoiceServiceTest
Run tests for a single target framework:
dotnet test src --framework net8.0
The library uses dotnet-format
for code formatting. Code
must be formatted before PRs are submitted, otherwise CI will fail. Run the
formatter with:
dotnet format src/Stripe.net.sln
For any requests, bug or comments, please open an issue or submit a pull request.