-
Notifications
You must be signed in to change notification settings - Fork 572
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
1 changed file
with
106 additions
and
93 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,146 +1,159 @@ | ||
| # Stripe.net | ||
| [](https://ci.appveyor.com/project/stripe/stripe-dotnet) [](https://www.nuget.org/packages/Stripe.net/) | ||
| [](https://www.nuget.org/packages/Stripe.net/) | ||
| [](https://ci.appveyor.com/project/stripe/stripe-dotnet) | ||
| [](https://coveralls.io/github/stripe/stripe-dotnet?branch=master) | ||
|
|
||
| The official Stripe library, supporting .NET Standard 1.2+, .NET Core 1.0+, and .NET Framework 4.5+ | ||
|
|
||
| ## Documentation | ||
|
|
||
| See the [.NET API docs](https://stripe.com/docs/api/dotnet#intro). | ||
| The official [Stripe][stripe] .NET library, supporting .NET Standard 1.2+, .NET Core 1.0+, and .NET Framework 4.5+. | ||
|
|
||
| ## Installation | ||
|
|
||
| ### Install Stripe.net via NuGet | ||
| Using the [.NET Core command-line interface (CLI) tools][dotnet-core-cli-tools]: | ||
|
|
||
| From the command line: | ||
| ```sh | ||
| dotnet install Stripe.net | ||
| ``` | ||
|
|
||
| nuget install Stripe.net | ||
| Using the [NuGet Command Line Interface (CLI)][nuget-cli]: | ||
|
|
||
| From Package Manager: | ||
| ```sh | ||
| nuget install Stripe.net | ||
| ``` | ||
|
|
||
| PM> Install-Package Stripe.net | ||
| Using the [Package Manager Console][package-manager-console]: | ||
|
|
||
| ```powershell | ||
| Install-Package Stripe.net | ||
| ``` | ||
|
|
||
| From within Visual Studio: | ||
|
|
||
| 1. Open the Solution Explorer. | ||
| 2. Right-click on a project within your solution. | ||
| 3. Click on *Manage NuGet Packages...* | ||
| 4. Click on the *Browse* tab and search for "Stripe.net". | ||
| 5. Click on the Stripe.net package, select the appropriate version in the right-tab and click *Install*. | ||
| 5. Click on the Stripe.net package, select the appropriate version in the | ||
| right-tab and click *Install*. | ||
|
|
||
| ### Set the API Key for your project | ||
| ## Documentation | ||
|
|
||
| You can configure the Stripe.net package to use your secret API key in one of two ways: | ||
| For a comprehensive list of examples, check out the [API | ||
| documentation][api-docs]. | ||
|
|
||
| a) In your application initialization, set your API key (only once once during startup): | ||
| ## Usage | ||
|
|
||
| ```csharp | ||
| StripeConfiguration.ApiKey = "[your api key here]"; | ||
| ``` | ||
| ### Per-request configuration | ||
|
|
||
| b) Pass the API key to [RequestOptions](#requestoptions): | ||
| All of the service methods accept an optional `RequestOptions` object. This is | ||
| used if you want to set an [idempotency key][idempotency-keys], if you are | ||
| using [Stripe Connect][connect-auth], or if you want to pass the secret API | ||
| key on each method. | ||
|
|
||
| ```csharp | ||
| var planService = new PlanService(); | ||
| planService.Get(*planId*, new RequestOptions { ApiKey = "[your api key here]" }); | ||
| ```c# | ||
| var requestOptions = new RequestOptions(); | ||
| requestOptions.ApiKey = "SECRET API KEY"; | ||
| requestOptions.IdempotencyKey = "SOME STRING"; | ||
| requestOptions.StripeAccount = "CONNECTED ACCOUNT ID"; | ||
| ``` | ||
|
|
||
| You can obtain your secret API key from the [API Settings](https://dashboard.stripe.com/account/apikeys) in the Dashboard. | ||
|
|
||
| ### Xamarin/Mono Developers (Optional) | ||
| ### Using a custom `HttpClient` | ||
|
|
||
| If you are using Xamarin/Mono, you may want to provide your own `HttpMessageHandler`. You can do so by passing an instance to `StripeConfiguration.HttpMessageHandler` on your application's startup. See [this thread](https://github.com/stripe/stripe-dotnet/issues/567) for details. | ||
| You can configure the library with your own custom `HttpClient`: | ||
|
|
||
| ## Additional Resources | ||
| ```c# | ||
| StripeConfiguration.StripeClient = new StripeClient( | ||
| new SystemNetHttpClient(httpClient)); | ||
| ``` | ||
|
|
||
| - [Stripe.net Fundamentals with ASP.NET (MVC)](https://app.pluralsight.com/library/courses/stripe-fundamentals-with-asp-net-mvc) [_PluralSight: Craig McKeachie_] | ||
| For example, you can use this to send requests to Stripe's API through a proxy | ||
| server: | ||
|
|
||
| ## Support | ||
| ```c# | ||
| using System.Net; | ||
| using System.Net.Http; | ||
| using Stripe; | ||
|
|
||
| * Make sure to review open [issues](https://github.com/stripe/stripe-dotnet/issues) and [pull requests](https://github.com/stripe/stripe-dotnet/pulls) before opening a new issue. | ||
| * Feel free to leave a comment or [reaction](https://github.com/blog/2119-add-reactions-to-pull-requests-issues-and-comments) on any existing issues. | ||
| * For all other support requests, please [reach out to Stripe](https://support.stripe.com/email) via email. | ||
| var handler = new HttpClientHandler | ||
| { | ||
| Proxy = new WebProxy(proxyUrl), | ||
| }; | ||
| var httpClient = new System.Net.HttpClient(handler); | ||
|
|
||
| ## Helpful Library Information | ||
| StripeConfiguration.StripeClient = new StripeClient( | ||
| new SystemNetHttpClient(httpClient)); | ||
| ``` | ||
|
|
||
| ### Request Options | ||
| ### Configuring automatic retries | ||
|
|
||
| All of the service methods accept an optional `RequestOptions` object. This is used if you need an [Idempotency Key](https://stripe.com/docs/api?lang=curl#idempotent_requests), if you are using [Stripe Connect](https://stripe.com/docs/connect/authentication#authentication-via-the-stripe-account-header), or if you want to pass the secret API key on each method. | ||
| The library can be configured to automatically retry requests that fail due to | ||
| an intermittent network problem or other knowingly non-deterministic errors: | ||
|
|
||
| ```csharp | ||
| var requestOptions = new RequestOptions(); | ||
| requestOptions.ApiKey = "SECRET API KEY"; // (optional) set the api key on a per-request basis | ||
| requestOptions.IdempotencyKey = "SOME STRING"; // (optional) create an idempotent request | ||
| requestOptions.StripeConnectAccountId = "CONNECTED ACCOUNT ID"; // (optional) authenticate as a connected account | ||
| ```c# | ||
| StripeConfiguration.MaxNetworkRetries = 2; | ||
| ``` | ||
|
|
||
| ### Responses | ||
| [Idempotency keys][idempotency-keys] are added to requests to guarantee that | ||
| retries are safe. | ||
|
|
||
| The [`StripeResponse`](./src/Stripe.net/Infrastructure/public/StripeResponse.cs) object is an attribute (with the same name) attached to all entities in Stripe.net when they are returned from a service call. | ||
| ### Writing a plugin | ||
|
|
||
| **Example: Access the StripeResponse** | ||
| ```csharp | ||
| var chargeService = new ChargeService(); | ||
| StripeCharge charge = chargeService.Create(...); | ||
| StripeResponse response = charge.StripeResponse; | ||
| ``` | ||
| If you're writing a plugin that uses the library, we'd appreciate it if you | ||
| identified using `StripeConfiguration.AppInfo`: | ||
|
|
||
| The information that can be derived from the `StripeResponse` is available from the [StripeResponse Class](https://github.com/stripe/stripe-dotnet/blob/master/src/Stripe.net/Infrastructure/Public/StripeResponse.cs). | ||
|
|
||
| ```csharp | ||
| public class StripeResponse | ||
| ```c# | ||
| StripeConfiguration.AppInfo = new AppInfo | ||
| { | ||
| // ResponseJson contains the complete JSON string Stripe returned to Stripe.net. | ||
| public string ResponseJson { get; set; } | ||
|
|
||
| // this is the request id of the call, as seen in the Stripe dashboard. I would recommend logging | ||
| // this and/or saving it to your database. this is very useful to help you find your request | ||
| // in the dashboard, or ask Stripe a question about your api call | ||
| public string RequestId { get; set; } | ||
|
|
||
| // this is the request date and time of the call. I would also recommend logging this and/or | ||
| // saving it to your database, as it tells you when Stripe processed the request. | ||
| public DateTime RequestDate { get; set; } | ||
| } | ||
| Name = "MyAwesomePlugin", | ||
| Url = "https://myawesomeplugin.info", | ||
| Version = "1.2.34", | ||
| }; | ||
| ``` | ||
|
|
||
| ### Date Filtering | ||
| 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. | ||
|
|
||
| Many of the `List()`-methods support parameters to filter by date. You can use the `DateFilter` class to combine the filters to make more interesting and complex queries. | ||
| ## Development | ||
|
|
||
| **Example: Interesting Queries with DateFilter** | ||
| ```csharp | ||
| var chargeService = new ChargeService(); | ||
| The test suite depends on [stripe-mock][stripe-mock], so make sure to fetch | ||
| and run it from a background terminal | ||
| ([stripe-mock's README][stripe-mock-usage] also contains instructions for | ||
| installing via Homebrew and other methods): | ||
|
|
||
| var chargesToday = chargeService.List(new ChargeListOptions { | ||
| Created = new DateFilter { GreaterThanOrEqual = DateTime.UtcNow.Date } | ||
| }); | ||
|
|
||
| var chargesYesterday = chargeService.List(new ChargeListOptions { | ||
| Created = new DateFilter { | ||
| GreaterThanOrEqual = DateTime.Now.AddDays(-1).Date, | ||
| LessThan = DateTime.Now.Date | ||
| } | ||
| }); | ||
| ```sh | ||
| go get -u github.com/stripe/stripe-mock | ||
| stripe-mock | ||
| ``` | ||
|
|
||
| ### Writing a Plugin | ||
|
|
||
| If you're writing a plugin that uses the library, we'd appreciate it if you identified using `StripeConfiguration.AppInfo`: | ||
| Run all tests: | ||
|
|
||
| ```c# | ||
| StripeConfiguration.AppInfo = new AppInfo | ||
| { | ||
| Name = "MyAwesomePlugin", | ||
| URL = "https://myawesomeplugin.info", | ||
| Version = "1.2.34", | ||
| }; | ||
| ```sh | ||
| dotnet test | ||
| ``` | ||
|
|
||
| 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. | ||
| Run some tests, filtering by name: | ||
|
|
||
| ## Contribution Guidelines | ||
| ``` | ||
| dotnet test --filter FullyQualifiedName~InvoiceServiceTest | ||
| ``` | ||
|
|
||
| We welcome contributions from anyone interested in Stripe or Stripe.net development. If you'd like to submit a pull request, it's best to start with an issue to describe what you'd like to build. | ||
| Run tests for a single target framework: | ||
|
|
||
| ```sh | ||
| dotnet test --framework netcoreapp2.1 | ||
| ``` | ||
|
|
||
| Once you've written your pull request, **please make sure you test your changes**. | ||
| For any requests, bug or comments, please [open an issue][issues] or [submit a | ||
| pull request][pulls]. | ||
|
|
||
| [api-docs]: https://stripe.com/docs/api?lang=dotnet | ||
| [api-keys]: https://dashboard.stripe.com/apikeys | ||
| [connect-auth]: https://stripe.com/docs/connect/authentication#authentication-via-the-stripe-account-header | ||
| [dotnet-core-cli-tools]: https://docs.microsoft.com/en-us/dotnet/core/tools/ | ||
| [idempotency-keys]: https://stripe.com/docs/api/idempotent_requests?lang=dotnet | ||
| [issues]: https://github.com/stripe/stripe-dotnet/issues/new | ||
| [nuget-cli]: https://docs.microsoft.com/en-us/nuget/tools/nuget-exe-cli-reference | ||
| [package-manager-console]: https://docs.microsoft.com/en-us/nuget/tools/package-manager-console | ||
| [pulls]: https://github.com/stripe/stripe-dotnet/pulls | ||
| [stripe]: https://stripe.com | ||
| [stripe-mock]: https://github.com/stripe/stripe-mock | ||
| [stripe-mock-usage]: https://github.com/stripe/stripe-mock#usage |