OCC-63: Separate Stripe payment into a feature so it can be disabled if other payment provider is desired.

.github/actions/spelling/allow/occ.txt

@@ -9,6 +9,7 @@ CLA
 contentpart
 CVC
 datetimefield
+deserializers
 disqus
 emoji
 EUR
@@ -27,8 +28,8 @@ pricefield
 roadmap
 shoppingcart
 skus
+testdiscountedproduct
 testproduct
 testproductvariant
-testdiscountedproduct
 unpublish
 webhooks

.github/actions/spelling/excludes.txt

@@ -4,7 +4,7 @@ docs/releases
 docs/requirements\.txt$
 mkdocs\.yml$
 src/Libraries/OrchardCore\.Commerce\.MoneyDataType/Currency\.extra\.cs$
-src/Modules/OrchardCore\.Commerce/Constants/CurrencyCollectionConstants\.cs$
-src/Modules/OrchardCore\.Commerce/Extensions/PaymentExtensions\.cs$
+src/Modules/OrchardCore\.Commerce\.Payment/Constants/CurrencyCollectionConstants\.cs$
+src/Modules/OrchardCore\.Commerce\.Payment\.Stripe/Extensions/PaymentExtensions\.cs$
 test/OrchardCore\.Commerce\.Tests/Fakes/AnkhMorporkCurrencyProvider\.cs$
 test/OrchardCore\.Commerce\.Tests/ProductAttributeTests\.cs$

OrchardCore.Commerce.sln

@@ -77,12 +77,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "features", "features", "{9B
 		docs\features\tiered-price-part.md = docs\features\tiered-price-part.md
 		docs\features\user-features.md = docs\features\user-features.md
 		docs\features\workflows.md = docs\features\workflows.md
-	EndProjectSection
-EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "releases", "releases", "{E4DD8D47-02FA-41F7-8133-CBC4419645F5}"
-	ProjectSection(SolutionItems) = preProject
-		docs\releases\0.0.1.md = docs\releases\0.0.1.md
-		docs\releases\1.0.0.md = docs\releases\1.0.0.md
+		docs\features\payment-providers.md = docs\features\payment-providers.md
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "actions", "actions", "{83C01924-6F58-4777-A9EC-07943F7A2E31}"
@@ -108,6 +103,12 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "libraries", "libraries", "{
 		docs\resources\libraries\README.md = docs\resources\libraries\README.md
 	EndProjectSection
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OrchardCore.Commerce.Payment", "src\Modules\OrchardCore.Commerce.Payment\OrchardCore.Commerce.Payment.csproj", "{58DD682C-DA5C-4B51-BCB8-C65D690AAC67}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OrchardCore.Commerce.Payment.Stripe", "src\Modules\OrchardCore.Commerce.Payment.Stripe\OrchardCore.Commerce.Payment.Stripe.csproj", "{A4D69733-CDC0-46AE-B46A-163CCC6F77F9}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "OrchardCore.Commerce.Abstractions", "src\Libraries\OrchardCore.Commerce.Abstractions\OrchardCore.Commerce.Abstractions.csproj", "{28DB6CBB-1527-42A1-8EFE-3D95BF185884}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -158,6 +159,18 @@ Global
 		{3DB5D0DD-1509-40B8-AD1A-47D5672BF484}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{3DB5D0DD-1509-40B8-AD1A-47D5672BF484}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{3DB5D0DD-1509-40B8-AD1A-47D5672BF484}.Release|Any CPU.Build.0 = Release|Any CPU
+		{58DD682C-DA5C-4B51-BCB8-C65D690AAC67}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{58DD682C-DA5C-4B51-BCB8-C65D690AAC67}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{58DD682C-DA5C-4B51-BCB8-C65D690AAC67}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{58DD682C-DA5C-4B51-BCB8-C65D690AAC67}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A4D69733-CDC0-46AE-B46A-163CCC6F77F9}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A4D69733-CDC0-46AE-B46A-163CCC6F77F9}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A4D69733-CDC0-46AE-B46A-163CCC6F77F9}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A4D69733-CDC0-46AE-B46A-163CCC6F77F9}.Release|Any CPU.Build.0 = Release|Any CPU
+		{28DB6CBB-1527-42A1-8EFE-3D95BF185884}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{28DB6CBB-1527-42A1-8EFE-3D95BF185884}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{28DB6CBB-1527-42A1-8EFE-3D95BF185884}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{28DB6CBB-1527-42A1-8EFE-3D95BF185884}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -177,13 +190,15 @@ Global
 		{87C422CA-C6F2-408F-987B-C8418995A331} = {E6C02BDF-EEB0-4ABD-ADEC-9932F60923AE}
 		{93871E12-0083-4323-BB7B-3CDA6E332D87} = {E6C02BDF-EEB0-4ABD-ADEC-9932F60923AE}
 		{9B2DB1CD-2B4A-4823-9762-CF4E90661404} = {BEBA1764-178A-4722-A193-4DEF26DCE8D1}
-		{E4DD8D47-02FA-41F7-8133-CBC4419645F5} = {BEBA1764-178A-4722-A193-4DEF26DCE8D1}
 		{83C01924-6F58-4777-A9EC-07943F7A2E31} = {4561F321-6E57-484B-950C-AC46798B1F40}
 		{E32B62B8-D737-4713-87C5-8220C9746643} = {83C01924-6F58-4777-A9EC-07943F7A2E31}
 		{7FB7940D-EEF4-4355-BCBF-C160080F257A} = {E32B62B8-D737-4713-87C5-8220C9746643}
 		{3DB5D0DD-1509-40B8-AD1A-47D5672BF484} = {772AFE42-DF1F-49B1-9F64-7C901E588C00}
 		{62DF9FF9-D2B3-4333-948D-2E405699B47B} = {BEBA1764-178A-4722-A193-4DEF26DCE8D1}
 		{C788AFFF-F440-4259-9102-5B4C1B91FAFA} = {62DF9FF9-D2B3-4333-948D-2E405699B47B}
+		{58DD682C-DA5C-4B51-BCB8-C65D690AAC67} = {E6C02BDF-EEB0-4ABD-ADEC-9932F60923AE}
+		{A4D69733-CDC0-46AE-B46A-163CCC6F77F9} = {E6C02BDF-EEB0-4ABD-ADEC-9932F60923AE}
+		{28DB6CBB-1527-42A1-8EFE-3D95BF185884} = {90913510-3D7F-4BCC-B55E-56343128F049}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {456CBC78-579D-483F-A4C3-AF5C12AB3324}

Readme.md

@@ -30,15 +30,16 @@ This project uses `Lombiq Node.js Extensions` to compile and lint client-side as
 2. Build and run the `OrchardCore.Commerce.Web` project.
 3. Thanks to [Auto Setup](https://docs.orchardcore.net/en/latest/docs/reference/modules/AutoSetup/), the site will be set up with the `OrchardCore Commerce - Development` recipe.
 4. Go to the dashboard, using the credentials `admin` and `Password1!`.
-5. Go to _Configuration_ → _Commerce_ → _Stripe API_. Set the keys to the test keys found [here](docs/features/stripe-payment.md). If the keys are not set, payment won't work.
+5. If you want to test Stripe, go to _Configuration_ → _Commerce_ → _Stripe API_. Set the keys to the test keys found [here](docs/features/stripe-payment.md). If the keys are not set, the Stripe payment button won't appear during checkout. 
 6. Go to _Content_ → _Content Items_, and create your first `Product`.
 
 ## Documentation
 
 - [Inventory](docs/features/inventory.md)
 - [Products and Prices](docs/features/products-and-prices.md)
 - [Promotions](docs/features/promotions.md)
-- [Stripe Payment](docs/features/stripe-payment.md)
+- [Payment providers](docs/features/payment-providers.md)
+  - [Stripe Payment](docs/features/stripe-payment.md)
 - [Taxation](docs/features/taxation.md)
 - [User Features](docs/features/user-features.md)
 - [Workflows](docs/features/workflows.md)

docs/features/payment-providers.md

@@ -0,0 +1,20 @@
+# Payment Providers
+
+Orchard Core Commerce supports multiple payment providers and allows developers to extend it further with their own.
+
+## Official payment providers
+
+Each provider is a stand-alone feature you can turn on or off.
+
+- [Stripe](stripe-payment.md): A production-ready provider for [stripe.com](https://stripe.com/).
+- Dummy: A development-only provider that lets you click through the checkout without going off-site. Mainly used for UI testing.
+
+## Creating your own
+
+To create a custom payment provider your code must contain the following:
+- An implementation of `IPaymentProvider` registered as a service.
+- A shape type `Checkout{provider.Name}`, such as _CheckoutStripe.cshtml_ and _CheckoutDummy.cshtml_.
+
+The `IPaymentProvider` contains implementable methods used by the `CheckoutController`. To learn more about the individual methods in the interface, check out the individual methods' XML documentation.
+
+The shape has the payment button that will be displayed on the `~/checkout` screen. It's up to you to include the front-end logic that calls out to your payment processor and to provide a callback URL. For the latter you can use the `~/checkout/callback/{providerName}/{orderId?}` action. It handles some basic state checking and redirection, but otherwise lets you resolve the pending order using `IPaymentProvider.UpdateAndRedirectToFinishedOrderAsync()`.

docs/features/stripe-payment.md

@@ -1,6 +1,6 @@
 # Stripe Payment
 
-Orchard Core Commerce [aims to support multiple payment providers](https://github.com/OrchardCMS/OrchardCore.Commerce/issues/149), but at this time [Stripe](https://stripe.com/) is the only supported implementation. This document describes how to set it up for testing, but if you just want to try out the checkout flow you can use the [cards](#cards) listed below without any configuration.
+Orchard Core Commerce supports multiple [payment providers](payment-providers.md). [Stripe](https://stripe.com/) was the first implemented. This document describes how to set it up for testing, including hooking your site up to the Stripe dashboard. If you just want to try out the checkout flow you can skip the Webhook sections.
 
 ## Test data for Stripe Payment
 
@@ -14,13 +14,15 @@ Stripe API uses a secret-publishable key pair. The following API keys are public
 
 **Publishable and secret keys are just publicly available test keys. Don't submit any personally identifiable information in requests made with this key.**
 
-You can obtain your own test keys from the Stripe dashboard. You can find them at _Dashboard → Developers → API keys_.
+You can obtain your own test keys from the Stripe dashboard. You can find them in the [developer dashboard's Api keys tab](https://dashboard.stripe.com/test/apikeys).
+
+In your Orchard Core site go to _Admin_ → _Configuration_ → _Commerce_ → _Stripe API_ and provide at least the _Publishable key_ and _Secret key_. Otherwise the feature can't work and the payment button will be hidden during checkout.
 
 ### Webhook signing key
 
 It is not needed, but recommended to use webhook. Otherwise, if there is a problem with redirecting the user, the payment confirmation will fail.
 
-There is no publicly available webhook signing key. Use your own API keys and Webhook key. Create your own at _Dashboard → Developers → Webhooks_.
+There is no publicly available webhook signing key. Use your own API keys and Webhook key. You can create one in the [developer dashboard's Webhooks tab](https://dashboard.stripe.com/test/webhooks).
 
 Read about webhook status codes [here](https://stripe.com/docs/webhooks/best-practices#pending-webhook-statuses). Our webhook endpoint returns _200_ if the request was received without an exception. It does not mean that it has been processed. It returns _400_ if there was an exception inside the webhook controller. Everything else comes from Stripe itself.
 

src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/ICheckoutEvents.cs

@@ -0,0 +1,16 @@
+using OrchardCore.Commerce.Abstractions.Models;
+using System.Threading.Tasks;
+
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
+
+/// <summary>
+/// Extension points for events related to checkout.
+/// </summary>
+public interface ICheckoutEvents
+{
+    /// <summary>
+    /// Invoked at the start of a new <see cref="OrderPart"/> creation which is used to create the <see
+    /// cref="ICheckoutViewModel"/>.
+    /// </summary>
+    Task OrderCreatingAsync(OrderPart orderPart, string shoppingCartId) => Task.CompletedTask;
+}

src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/ICheckoutViewModel.cs

@@ -0,0 +1,21 @@
+using Microsoft.AspNetCore.Mvc.Rendering;
+using OrchardCore.Commerce.MoneyDataType;
+using OrchardCore.DisplayManagement;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
+
+[SuppressMessage(
+    "StyleCop.CSharp.DocumentationRules",
+    "SA1600:Elements should be documented",
+    Justification = "Nothing to say besides what's already on the property names.")]
+public interface ICheckoutViewModel : IPaymentViewModel, IShape
+{
+    string ShoppingCartId { get; }
+    Amount GrossTotal { get; }
+    IEnumerable<SelectListItem> Regions { get; set; }
+    IDictionary<string, IDictionary<string, string>> Provinces { get; }
+    string UserEmail { get; }
+    IEnumerable<IShape> CheckoutShapes { get; }
+}

src/Modules/OrchardCore.Commerce/Abstractions/ILineItem.cs → src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/ILineItem.cs

@@ -1,6 +1,6 @@
 using OrchardCore.Commerce.MoneyDataType;
 
-namespace OrchardCore.Commerce.Abstractions;
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
 
 /// <summary>
 /// Represents an object that contains some of an order line item's basic info.

src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/IOrderEvents.cs

@@ -0,0 +1,27 @@
+using OrchardCore.Commerce.Abstractions.Models;
+using OrchardCore.Commerce.Abstractions.ViewModels;
+using OrchardCore.ContentManagement;
+using System.Threading.Tasks;
+
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
+
+/// <summary>
+/// Extension points for events related to orders.
+/// </summary>
+public interface IOrderEvents
+{
+    /// <summary>
+    /// Invoked when a new free (non-payment) order is created.
+    /// </summary>
+    Task CreatedFreeAsync(OrderPart orderPart, ShoppingCart cart, ShoppingCartViewModel viewModel) => Task.CompletedTask;
+
+    /// <summary>
+    /// Invoked when the <paramref name="order"/> is set to the <c>Ordered</c> state.
+    /// </summary>
+    Task OrderedAsync(ContentItem order, string shoppingCartId) => Task.CompletedTask;
+
+    /// <summary>
+    /// Invoked during cleanup after the order has been finalized.
+    /// </summary>
+    Task FinalizeAsync(ContentItem order, string shoppingCartId, string paymentProviderName) => Task.CompletedTask;
+}

src/Modules/OrchardCore.Commerce/Abstractions/IPayment.cs → src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/IPayment.cs

@@ -1,7 +1,7 @@
 using OrchardCore.Commerce.MoneyDataType;
 using System;
 
-namespace OrchardCore.Commerce.Abstractions;
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
 
 /// <summary>
 /// Describes a payment transaction's details.

src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/IPaymentViewModel.cs

@@ -0,0 +1,18 @@
+using OrchardCore.Commerce.Abstractions.Models;
+using OrchardCore.Commerce.MoneyDataType;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
+
+[SuppressMessage(
+    "StyleCop.CSharp.DocumentationRules",
+    "SA1600:Elements should be documented",
+    Justification = "Nothing to say besides what's already on the property names.")]
+public interface IPaymentViewModel
+{
+    Amount SingleCurrencyTotal { get; }
+    Amount NetTotal { get; }
+    IDictionary<string, object> PaymentProviderData { get; }
+    OrderPart OrderPart { get; }
+}

src/Modules/OrchardCore.Commerce/Abstractions/IPredefinedValuesProductAttributeValue.cs → src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/IPredefinedValuesProductAttributeValue.cs

@@ -1,4 +1,4 @@
-namespace OrchardCore.Commerce.Abstractions;
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
 
 /// <summary>
 /// Represents a predefined <see cref="IProductAttributeValue"/> with no type specified.

src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/IProductAttributeDeserializer.cs

@@ -0,0 +1,49 @@
+using Newtonsoft.Json.Linq;
+using System;
+using System.Collections.Generic;
+using System.Text.Json.Nodes;
+
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
+
+/// <summary>
+/// Deserializes the attribute of the type <see cref="AttributeTypeName"/>.
+/// </summary>
+public interface IProductAttributeDeserializer
+{
+    // Not necessary to document as they are not externally accessible.
+#pragma warning disable SA1600 // Elements should be documented.
+    internal static readonly Dictionary<string, IProductAttributeDeserializer> Deserializers =
+        new(StringComparer.OrdinalIgnoreCase);
+
+    private static readonly object _lock = new();
+#pragma warning restore SA1600
+
+    /// <summary>
+    /// Gets the attribute name used to identify this deserializer.
+    /// </summary>
+    string AttributeTypeName { get; }
+
+    /// <summary>
+    /// Deserializes using <c>Newtonsoft.Json</c>.
+    /// </summary>
+    IProductAttributeValue Deserialize(string attributeName, JObject attribute);
+
+    /// <summary>
+    /// Deserializes using <c>System.Text.Json</c>.
+    /// </summary>
+    IProductAttributeValue Deserialize(string attributeName, JsonObject attribute);
+
+    /// <summary>
+    /// Registers serializers used to deserialize product attributes.
+    /// </summary>
+    public static void AddSerializers(params IProductAttributeDeserializer[] deserializers)
+    {
+        lock (_lock)
+        {
+            foreach (var deserializer in deserializers)
+            {
+                Deserializers[deserializer.AttributeTypeName] = deserializer;
+            }
+        }
+    }
+}

src/Modules/OrchardCore.Commerce/Abstractions/IProductAttributeValue.cs → src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/IProductAttributeValue.cs

@@ -1,10 +1,10 @@
 using Newtonsoft.Json;
-using OrchardCore.Commerce.Serialization;
+using OrchardCore.Commerce.Abstractions.Serialization;
 using System;
 using System.Globalization;
 using System.Linq;
 
-namespace OrchardCore.Commerce.Abstractions;
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
 
 /// <summary>
 /// A specific value from a product attribute field.

src/Modules/OrchardCore.Commerce/Abstractions/IRegionService.cs → src/Libraries/OrchardCore.Commerce.Abstractions/Abstractions/IRegionService.cs

@@ -3,7 +3,7 @@
 using System.Globalization;
 using System.Threading.Tasks;
 
-namespace OrchardCore.Commerce.Abstractions;
+namespace OrchardCore.Commerce.Abstractions.Abstractions;
 
 /// <summary>
 /// A service for accessing and customizing regions.