Improved OAuth support (#1542)

src/Stripe.net/Entities/OAuth/OAuthDeauthorize.cs

@@ -4,13 +4,12 @@ namespace Stripe
 
     public class OAuthDeauthorize : StripeEntity<OAuthDeauthorize>
     {
+        /// <summary>
+        /// The unique id of the account you have revoked access to, as a string. This is the same
+        /// as the <see cref="OAuthDeauthorizeOptions.StripeUserId"/> you passed in. If this is
+        /// returned, the revocation was successful.
+        /// </summary>
         [JsonProperty("stripe_user_id")]
         public string StripeUserId { get; set; }
-
-        [JsonProperty("error")]
-        public string Error { get; set; }
-
-        [JsonProperty("error_description")]
-        public string ErrorDescription { get; set; }
     }
 }

src/Stripe.net/Entities/OAuth/OAuthToken.cs

@@ -1,34 +1,84 @@
 namespace Stripe
 {
+    using System;
     using Newtonsoft.Json;
 
     public class OAuthToken : StripeEntity<OAuthToken>
     {
-        [JsonProperty("token_type")]
-        public string TokenType { get; set; }
-
-        [JsonProperty("scope")]
-        public string Scope { get; set; }
+        /// <summary>
+        /// <para>
+        /// The access token you can use to make requests on behalf of this Stripe account. Use it
+        /// as you would any Stripe secret API key.
+        /// </para>
+        /// <para>
+        /// This key does not expire, but may be revoked by the user at any time (you'll get a
+        /// <c>account.application.deauthorized</c>
+        /// <see href="https://stripe.com/docs/api/events/types#event_types-account.application.authorized">webhook event</see>
+        /// when this happens).
+        /// </para>
+        /// </summary>
+        /// <remarks>
+        /// This property is deprecated. In backend code, it is recommended that you use your own
+        /// secret key in conjunction with the connected account's ID found in
+        /// <see cref="StripeUserId"/>.
+        /// </remarks>
+        [Obsolete("Use StripeUserId instead.")]
+        [JsonProperty("access_token")]
+        public string AccessToken { get; set; }
 
+        /// <summary>
+        /// <para>
+        /// The live mode indicator for the token. If <c>true</c>, the <see cref="AccessToken"/>
+        /// can be used as a live secret key. If <c>false</c>, the <see cref="AccessToken"/> can be
+        /// used as a test secret key.
+        /// </para>
+        /// <para>Depends on the mode of the secret API key used to make the request.</para>
+        /// </summary>
         [JsonProperty("livemode")]
         public bool Livemode { get; set; }
 
-        [JsonProperty("stripe_user_id")]
-        public string StripeUserId { get; set; }
-
-        [JsonProperty("stripe_publishable_key")]
-        public string StripePublishableKey { get; set; }
-
+        /// <summary>
+        /// Can be used to get a new access token of an equal or lesser scope, or of a different
+        /// live mode (where
+        /// <see href="https://stripe.com/docs/connect/testing#test-keys-for-livemode-applications">applicable</see>).
+        /// </summary>
+        /// <remarks>
+        /// This property is deprecated. In backend code, it is recommended that you don't use
+        /// access tokens or refresh tokens at all. Instead, you should use your own secret key in
+        /// conjunction with the connected account's ID found in <see cref="StripeUserId"/>.
+        /// </remarks>
+        [Obsolete("Use StripeUserId instead.")]
         [JsonProperty("refresh_token")]
         public string RefreshToken { get; set; }
 
-        [JsonProperty("access_token")]
-        public string AccessToken { get; set; }
+        /// <summary>
+        /// The scope granted to the access token, depending on the scope of the authorization code
+        /// and <c>scope</c> parameter.
+        /// </summary>
+        [JsonProperty("scope")]
+        public string Scope { get; set; }
+
+        /// <summary>
+        /// A publishable key that can be used with this account. Matches the mode—live or test—of
+        /// the token.
+        /// </summary>
+        /// <remarks>
+        /// This property is deprecated. In frontend code, it is recommended that you use your own
+        /// publishable key in conjunction with the connected account's ID found in
+        /// <see cref="StripeUserId"/>.
+        /// </remarks>
+        [Obsolete("Use StripeUserId instead.")]
+        [JsonProperty("stripe_publishable_key")]
+        public string StripePublishableKey { get; set; }
 
-        [JsonProperty("error")]
-        public string Error { get; set; }
+        /// <summary>
+        /// The unique id of the account you have been granted access to, as a string.
+        /// </summary>
+        [JsonProperty("stripe_user_id")]
+        public string StripeUserId { get; set; }
 
-        [JsonProperty("error_description")]
-        public string ErrorDescription { get; set; }
+        /// <summary>Will always have a value of <c>bearer</c>.</summary>
+        [JsonProperty("token_type")]
+        public string TokenType { get; set; }
     }
 }

src/Stripe.net/Infrastructure/Public/StripeClient.cs

@@ -109,7 +109,7 @@ private static StripeException BuildStripeException(StripeResponse response)
             return new StripeException(
                 response.StatusCode,
                 stripeError,
-                stripeError.Message)
+                stripeError.Message ?? stripeError.ErrorDescription)
             {
                 StripeResponse = response,
             };

src/Stripe.net/Infrastructure/Public/StripeConfiguration.cs

@@ -12,6 +12,7 @@ namespace Stripe
     public static class StripeConfiguration
     {
         private static string apiKey;
+        private static string clientId;
 
         private static IStripeClient stripeClient;
 
@@ -73,6 +74,31 @@ public static string ApiKey
             set => apiKey = value;
         }
 
+#if NET45 || NETSTANDARD2_0
+        /// <summary>Gets or sets the client ID.</summary>
+        /// <remarks>
+        /// You can also set the client ID using the <c>StripeClientId</c> key in
+        /// <see cref="System.Configuration.ConfigurationManager.AppSettings"/>.
+        /// </remarks>
+#else
+        /// <summary>Gets or sets the client ID.</summary>
+#endif
+        public static string ClientId
+        {
+            get
+            {
+#if NET45 || NETSTANDARD2_0
+                if (string.IsNullOrEmpty(apiKey))
+                {
+                    clientId = System.Configuration.ConfigurationManager.AppSettings["StripeClientId"];
+                }
+#endif
+                return clientId;
+            }
+
+            set => clientId = value;
+        }
+
         /// <summary>Gets or sets the base URL for Stripe's OAuth API.</summary>
         public static string ConnectBase { get; set; } = DefaultConnectBase;
 

src/Stripe.net/Services/OAuth/OAuthAuthorizeUrlOptions.cs

@@ -0,0 +1,88 @@
+namespace Stripe
+{
+    using System.Collections.Generic;
+    using Newtonsoft.Json;
+
+    public class OAuthAuthorizeUrlOptions : BaseOptions
+    {
+        /// <summary>
+        /// Boolean to indicate that the user should always be asked to connect, even if they're
+        /// already connected. Defaults to <c>false</c>.
+        /// </summary>
+        [JsonProperty("always_prompt")]
+        public bool? AlwaysPrompt { get; set; }
+
+        /// <summary>
+        /// The unique identifier provided to your application, found in your
+        /// <see href="https://dashboard.stripe.com/account/applications/settings">application settings</see>.
+        /// </summary>
+        [JsonProperty("client_id")]
+        public string ClientId { get; set; } = StripeConfiguration.ClientId;
+
+        /// <summary>The only option at the moment is <c>code</c>.</summary>
+        [JsonProperty("response_type")]
+        public string ResponseType { get; set; } = "code";
+
+        /// <summary>
+        /// <para>
+        /// The URL for the authorize
+        /// <see href="https://stripe.com/docs/connect/oauth-reference#get-authorize-response">response</see>
+        ///  redirect. If provided, this must exactly match one of the comma-separated
+        /// <c>redirect_uri</c> values in your
+        /// <see href="https://dashboard.stripe.com/account/applications/settings">application settings</see>.
+        /// </para>
+        /// <para>
+        /// To protect yourself from certain forms of man-in-the-middle attacks, the live mode
+        /// <c>redirect_uri</c> must use a secure HTTPS connection.
+        /// </para>
+        /// <para>
+        /// Defaults to the <c>redirect_uri</c> in your application settings if not provided.
+        /// </para>
+        /// </summary>
+        [JsonProperty("redirect_uri")]
+        public string RedirectUri { get; set; }
+
+        /// <summary>
+        /// <c>read_write</c> or <c>read_only</c>, depending on the level of access you need.
+        /// Defaults to <c>read_only</c>.
+        /// </summary>
+        [JsonProperty("scope")]
+        public string Scope { get; set; }
+
+        /// <summary>
+        /// An arbitrary string value we will pass back to you, useful for CSRF protection.
+        /// </summary>
+        [JsonProperty("state")]
+        public string State { get; set; }
+
+        /// <summary>
+        /// <para>
+        /// <c>login</c> or <c>register</c>, depending on what type of screen you want your users
+        /// to see. Only override this to be <c>login</c> if you expect all your users to have
+        /// Stripe accounts already (e.g., most read-only applications, like analytics dashboards or
+        /// accounting software).
+        /// </para>
+        /// <para>
+        /// Defaults to <c>login</c> for scope <c>read_only</c> and <c>register</c> for scope
+        /// <c>read_write</c>.
+        /// </para>
+        /// </summary>
+        [JsonProperty("stripe_landing")]
+        public string StripeLanding { get; set; }
+
+        /// <summary>Prefilled details in the account form for new users.</summary>
+        [JsonProperty("stripe_user")]
+        public OAuthAuthorizeUrlStripeUserOptions StripeUser { get; set; }
+
+        /// <summary>
+        /// If your platform is designated for one
+        /// <see href="https://stripe.com/docs/connect/capabilities-overview">Capability</see>
+        /// (either <c>card_payments</c> or <c>platform_payments</c>), you won’t need to specify
+        /// additional Capabilities. However, if your platform supports both, you can add a
+        /// Capability to an individual Express account by including the
+        /// <see cref="SuggestedCapabilities"/> parameter in your OAuth link.
+        /// </summary>
+        [JsonProperty("suggested_capabilities")]
+        public List<string> SuggestedCapabilities { get; set; }
+    }
+}