payments

Reading Time: 7 minutes

In this article, we will review and compare tax and payments between Sitecore Experience Commerce and OrderCloud to facilitate developers looking to transition from XC to OrderCloud as well as identify a path for migration of existing XC solutions to OrderCloud.

We will look at a high-level comparison of architecture, functionality, and data models, with greater focus on transitioning from Sitecore Experience Commerce, meaning identifying a close path to parity in OrderCloud, using the Habitat catalog and SXA Storefront.

Conceptual Architecture and Features

Tax

The Commerce Engine’s tax plugin is considered sample code that is sufficient enough to support basic tax requirements, however tax calculations will typically be customised to support the tax provider integrations that cater to tax laws for the countries and/or regions the storefront will be servicing.

The following list contains highlights of the tax plugin:

Tax is calculated as a cart adjustment when a fulfillment component is applied to the cart.
Tax is calculated as a cart line adjustment where a fullfillment component exists on the cart line.
XC waits for a cart to contain a fulfillment component before calculating taxes, as the delivery address is intended to identify applicable tax laws, but not catered for without customisation.
Sellable item pricing does not include tax.
Applying the tag taxexempt will omit sellable items from tax calculations.
Tax is calculated as a flat rate, i.e. tax is not dynamically calculated based on country/region tax laws.

The GlobalTaxPolicy provides the configuration properties of the sample tax plugin.

{
  "$type": "Sitecore.Commerce.Plugin.Tax.GlobalTaxPolicy, Sitecore.Commerce.Plugin.Tax",
  "DefaultCartTaxRate": 0.1,
  "DefaultItemTaxRate": 0.1
  "TaxExemptTagsEnabled":true,
  "TaxExemptTag":"taxexempt",
  "TaxCalculationEnabled": true, // Not hooked up
  "PriceIncudesTax": false, // Not hooked up
  "CalculateTaxBasedOn": "ShippingAddress", // Not hooked up
  "ShippingTaxClass": "CartItems", // Not hooked up
  "RoundAtSubTotal": false // Not hooked up
}

When it comes to tax in the OrderCloud platform, it is unopinionated on the methods of which to achieve tax calculations due to the numerous unique tax regulations around the world. Instead, OrderCloud allows the implementer to address tax calculations via the order calculate integration event, whether it be through integrations third party tax providers or complete custom implementation.

Figure 1 shows an overview of the order calculate integration event implementation in regards to calculating taxes. OrderCloud’s /calculate endpoint forwards the request along with the order worksheet to the middleware’s /ordercalculate endpoint. The middleware will then construct and return the OrderCalculateResponse model, containing the calculated TaxTotal, which OrderCloud then copy to the order’s TaxCost property. To track line item level taxes, calculated taxes can be stored in the OrderCalculateResponse‘s xp.

The TaxCost is used in OrderCloud’s calculations of the order Total, i.e. Total = Subtotal + TaxCost + ShippingCost - PromotionDiscount.

Figure 1: *The order calculate integration event overview.*

The calling system in figure 1 may be the client-side storefront or the middleware, depending on the implementation details.

Gift Cards vs Spending Accounts

XC provides a gift card payment type, which is integrated into the SXA storefront checkout to demonstrate end-to-end functionality of gift card payments. It is treated as a sample implementation as the functionality in the Commerce Engine is typically replaced with an integration to a gift card payment provider.

Reviewing OrderCloud’s supported payment types, spending accounts most closely resemble XC’s gift card implementation as it has the ability to track the available funds. One minor difference is that spending accounts are created under the context of a buyer and is therefore tied to the buyer users within that buyer, whereas gift cards in XC are globally accessible.

To differentiate spending accounts representing gift cards from other spending account types, xp can be leveraged to specify the type.

Figure 2: Gift card architecture comparison.

Global Payment Configuration

In an XC SXA implementation, payments are configured at a global level under sitecore/Commerce/Commerce Control Panel/Shared Settings, as depicted in figure 3. The configuration is split across Payment Option Types and Payment Options and linked via the PaymentOption Type property on the payment option item, however there really isn’t any discernable difference between the two within the SXA/Commerce Engine implementation.

Figure 3: Payment option to payment option type in the Sitecore Content Editor.

Instead of a BYO payment types approach, OrderCloud has defined three payment types, being purchase order, credit card, and spending account, with each type serving a different approach to handling order payments. For example, the credit card payment type would integrate with a payment service provider for perform transactions, while the spending account manages a balance maintained purely with OrderCloud, including adjusting the balance upon successful order submission.

Figure 4: Payment architecture overview.

As XC contains multiple Payment Option Types that could map to a single OrderCloud payment type, xp can be leveraged to represent multiple sub-types. The following table shows how XC’s Payment Option Types could map to Payment Types in OrderCloud.

Payment Option Type (XC)	Payment Type (OrderCloud)	xp (OrderCloud)
Card Payment	Credit Card	xp.Type: “Basic Card”
Federated Payment	Credit Card	xp.Type: “Braintree”
Gift Card Payment	Spending Account	xp.Type: “Gift Card”
Loyalty Card Payment	Spending Account	xp.Type: “Loyalty Card”

More information on payment types can be found in OrderCloud: Flexible Fulfillment > Apply Payments.

Storefront Payment Configuration

Payment options are also configured against an SXA storefront with a subset of those configured in the Shared Settings.

While OrderCloud doesn’t have the context of storefronts, storefront-specific payment options will likely be a consideration for middleware’s logic for identifying applicable payments options.

Payment Components vs Payments

When it comes to the implementation, this is where the Commerce Engine plugins take the payment configurations and provide the functionality for the payment types. The sample Braintree plugin and the GiftCards plugin will add a FederatedPaymentComponent or a GiftCardComponent to the cart respectively, which will then be used to dictate how those payments are interacted with throughout the platform, during and post order creation.

OrderCloud uses the payments entity in a more concrete way, using the Type property to facilitate the payment behaviour. For example, selecting the spending account type will require the also specifying a spending account that is assigned to the buyer user via buyer or buyer user group assignment.

Figure 6: An order paid for using both a credit card and a gift card payment types.

Sales Activities vs Transactions

XC orders use sales activities to track the transaction activities of each order payment component while OrderCloud uses transactions for the same purpose.

Figure 7: Sales activities vs transaction architecture.

Functionality

The Storefront Checkout Billing Step

Turning our attention to the storefront functionality of the billing checkout steps from Carts to Unsubmitted Orders: Storefront User Journey, we will look at adding the email address and payment details to the cart/unsubmitted order, focusing on varying APIs of the two platforms.

Figure 8: The checkout billing aspects of the storefront user journey.

Viewing the interaction diagram in figure 9, the SXA storefront utilises the BillingDataJsonResult to provide the necessary data to render and facilitate payment option logic in the storefront. Once the user has submitted the payment details, all payment data is then sent to the Commerce Engine together to be added to the cart.

A few notes on the payment functionality:

Payments are only supported at the cart-level.
The email address is collected per order as the user may wish not to use the email address associated to their account (for registered users). This email is typically used for communications to the customer, such as email confirmation, invoicing, shipments, etc.
XC has logic to prevent a gift card sellable item to be purchased with a gift card payment.

Figure 9: The billing checkout step of the SXA storefront.

To replicate similar behaviour in an OrderCloud storefront implementation, figure 10 provides an approach to the billing checkout step.

The /paymentoptions middleware endpoint retrieves the applicable payment options for the order, dependent on the storefront and business requirements.
The email address is PATCHed to the order xp for specific order context.
All payments can be added to the order via ../payments endpoint; the data sent may differ based on payment type.

Figure 10: *An example approach for the delivery checkout step in an OrderCloud storefront.*

Data Mapping

With the conceptual analysis above, we will now review what data mapping would look like for migration and from a comparison standpoint.

In the XC Entity/Component column, components are assumed to live on the primary XC entity being mapped.

OrderCloud IDs do not allow spaces. It is important that the IDs are parsed to remove/replace invalid characters consistently.

Spending Accounts

The following mapping shows how XC’s default implementation of gift cards can be translated into OrderCloud using spending accounts.

OC Property	Data Type	Required	XC Entity/Component	XC Property	Data Type	Notes
buyerID	string	Yes	N/A	N/A	N/A
ID	string	No	GiftCard	GiftCardCode	string	Use format “GiftCard-<GiftCardCode>”
Name	string	Yes	GiftCard	Name	string
Balance	decimal	Yes	GiftCard	Balance.Amount	decimal
AllowAsPaymentMethod	boolean	No	N/A	N/A	N/A	Set to `true`.
RedemptionCode	string	No	GiftCard	GiftCardCode	string
StartDate	DateTimeOffset	No	GiftCard	ActivationDate	DateTimeOffset
EndDate	DateTimeOffset	No	N/A	N/A	N/A
xp	object	No	N/A	N/A	N/A
xp.Type	string	No	N/A	N/A	N/A	Set to `"GiftCard"`.
xp.InitialAmount	decimal	No	GiftCard	OriginalAmount.Amount	decimal
xp.Currency	string	No	GiftCard	OriginalAmount.CurrencyCode	string	Recommended for handling multi-currency validation.

Tag: payments

Transitioning from Sitecore Experience Commerce to OrderCloud: Tax and Payments