Set a Stripe API version

Setting the API version

Because C# is a strongly-typed programming language, the API version used in the .NET SDK is fixed and is the latest API version at the time of the SDK release.

We don’t recommend setting a different API version for strongly-typed programming languages, because the response objects might not match the strong types in the SDK and result in request failures. For example, if the API version you’re targeting requires parameters that aren’t present in the SDK types, the request fails.

Upgrading your API version

Before upgrading your API version, carefully review the following resources:

• Stripe API changelog
• View the API versions used by API requests

You can upgrade your account’s default API version in Workbench. Update your code to use the latest version of the .NET SDK to make sure all your requests target the latest API version.

Upgrading your webhook handlers for a new API version

During the upgrade process, we recommend creating and maintaining two webhook endpoints with two different API versions: one for your existing API version, and one for the API version that you want to upgrade to. This allows you to test your new code while maintaining the ability to safely roll back to your existing version if needed.

1. Write new webhook event handling code using the version of the SDK you want to upgrade to. When handling incoming events, store the raw body of the request from Stripe in a queue that’s processed sequentially.
2. Register a new webhook endpoint with the API version you’re upgrading to and point to your new webhooks URL. You can register a webhook endpoint in Workbench or with the API (as shown):

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
StripeConfiguration.ApiKey = 
"sk_test_BQokikJOvBiI2HlWgH4olfQ2";

var options = new WebhookEndpointCreateOptions
{
  Url = "https://example.com/my/webhook/endpoint",
  EnabledEvents = new List<String>
  {
    "payment_intent.succeeded",
    "payment_intent.payment_failed",
  },
  ApiVersion = "2020-03-02",
};
var service = new WebhookEndpointService();
var webhookEndpoint = service.Create(options);

• Be sure to test your webhooks integration (for example, use the Stripe CLI to trigger events). After you’re confident that your webhooks integration works as intended, you can start processing events in production and disable or delete your old webhook endpoint.

If you aren’t using an event queue, modify your old code to stop processing events and respond with a 400 HTTP status code. If the new code isn’t working as expected and you need to revert to the old code, turn the event processing logic back on and allow it to respond normally. Doing this within the 3-day rollback window ensures you’ll receive all the events retried without missing any.