Configured Commerce plug-ins

10 min

Optimizely Configured Commerce's plug-ins use a common architecture. Each one has a factory that uses the service locator to get the concrete type of the plug-in configured for the platform.

Configured Commerce has the following plug-ins:

Currency conversion

Geocode providers

Payment gateways

Product search

Rating services

Tax calculators

Translation services

Currency conversion

You can convert price values from one currency to another by implementing the ICurrencyConverter, which uses the GetRate() method. The GetRate() method takes the currency from and currency to parameters and returns the decimal value for that conversion.

public interface ICurrencyConverter : IDependency
{
    /// <summary>Get the conversion rate.</summary>
    /// <param name="currencyFrom">The from currency.</param>
    /// <param name="currencyTo">The to currency.</param>
    /// <returns>The exchange rate.</returns>
    decimal GetRate(string currencyFrom, string currencyTo);
}

Configured Commerce executes currency conversion using a post-processor currency refresh. You can configure the currency converter with the CurrencyConverter application setting, which uses the dependency name as the value.

Configured Commerce has two currency converters:

TheMoneyConvert

WebserviceX

Geocode

The geocode plug-in IGeocoderProvider evaluates a location or address and resolves it to a location object containing Latitude, Longitude, City, StateAbbreviation, CountryAbbreviation, and PostalCode. IGeocoderProvider uses the Geocode() method.

public interface IGeocoderProvider : IDependency
{
    /// <summary>Find lat/long coordinate from an address string.</summary>
    /// <param name="address">string to geocode. Accepted content will be implementation specific</param>
    /// <returns><see cref="LocationDto"/> lat/long point corresponding to the address.</returns>
    LocationDto Geocode(string address);
}

Configured Commerce has the following geolocation services:

Google

📘 Note The FreeGeoIP API has been decommissioned and is no longer available as a geolocation service.

Current location

The ICurrentLocationProvider plug-in resolves a shopper's current location for location-based rules, such as the Current Location rule type in the rules engine. ICurrentLocationProvider uses the GetCurrentLocation() method and returns a location object containing Latitude, Longitude, City, StateAbbreviation, CountryAbbreviation, and PostalCode.

Configured Commerce has one current location provider by default, ByIp, which resolves an anonymous shopper's location from Cloudflare's visitor location HTTP headers (cf-ipcity, cf-region-code, cf-postal-code, cf-ipcountry, cf-iplatitude, cf-iplongitude) instead of calling a third-party geolocation API.

📘 Note Enable the "Add visitor location headers" managed transform for the Cloudflare zone serving the site. If the transform is not enabled, latitude and longitude are not populated and a warning is logged to the application log.

Payment gateways

Configured Commerce processes orders through a payment gateway. The IPaymentGateway interface contains the following methods:

SubmitTransaction()

GetStoredPaymentProfile()

StorePaymentProfile()

RemoveStoredPaymentProfile()

public interface IPaymentGateway : IDependency
{
    /// <summary>
    /// Gets a value indicating whether the <see cref="IPaymentGateway"/> supports stored
    /// payment profiles.
    /// </summary>
    bool SupportsStoredPaymentProfiles { get; }

    /// <summary>Submits the requested transaction to the PaymentGateway.</summary>
    /// <param name="parameter">The parameter.</param>
    /// <returns>The <see cref="SubmitTransactionResult"/>.</returns>
    SubmitTransactionResult SubmitTransaction(SubmitTransactionParameter parameter);

    /// <summary>Gets the stored payment profiles for the user.</summary>
    /// <param name="parameter">The parameter.</param>
    /// <returns>The <see cref="GetStoredPaymentProfileResult"/>.</returns>
    GetStoredPaymentProfileResult GetStoredPaymentProfile(GetStoredPaymentProfileParameter parameter);

    /// <summary>Stores the payment information (normally Credit Card information) with
    /// the configured payment gateway and returns
    /// a token to use for future transactions.</summary>
    /// <param name="parameter">The parameter.</param>
    /// <returns>The <see cref="StorePaymentProfileResult"/>.</returns>
    StorePaymentProfileResult StorePaymentProfile(StorePaymentProfileParameter parameter);

    /// <summary>Removes the specified payment profile.</summary>
    /// <param name="parameter">The parameter.</param>
    /// <returns>The <see cref="RemoveStoredPaymentProfileResult"/>.</returns>
    RemoveStoredPaymentProfileResult RemoveStoredPaymentProfile(RemoveStoredPaymentProfileParameter parameter);
}

Configured Commerce has four payment gateway providers by default:

Authorize.NET

Cenpos

CyberSource

PayflowPro

The PaymentGateway application setting is set to the dependency name of the provider class. When the PaymentGateway is set to Dummy, you can use test credit card numbers when testing submitting orders.

Product search

Configured Commerce product search can use Solr or Lucene. Both search providers come from the ProductSearchProviderBase class. To set the search provider, set the application setting ProductSearchProvider to the name of the dependency value on the class of the provider.

Configured Commerce has the following search providers:

Azure Lucene

Lucene

Solr

See Get started with search ranking and relevance.

Rating services

Processing shipping is an important aspect of any commerce site, and Configured Commerce has two rating service providers, which implement the IRatingService interface. This interface implements the RateShipment() method and uses the parameters ship from address, customer order, packages, and carrier. RateShipment returns a list of shipping cost objects.

public interface IRatingService : IDependency
{
    /// <summary>
    /// Gets a value indicating whether the <see cref="IRatingService" /> support
    /// multicurrency natively.
    /// </summary>
    bool SupportsMultiCurrency { get; }

    /// <summary>Method that rates the shipment for the given list of Packages and
    /// Carrier</summary>
    /// <param name="shipFromAddress">The ship From Address.</param>
    /// <param name="customerOrder">The customer Order.</param>
    /// <param name="packages">List of Packages to rate for the Shipment normally
    /// returned from IOrderPackager</param>
    /// <param name="carrier">The Carrier to rate the Shipment for</param>
    /// <returns>List of ShippingCosts representing the different Services and Costs for
    /// shipping the Packages for the given Carrier</returns>
    IList<ShippingCost> RateShipment(
        ShipFromAddress shipFromAddress,
        CustomerOrder customerOrder,
        IList<Package> packages,
        Carrier carrier);
}

Configured Commerce uses the ship rating service in the GetCartHandler and CartHelper class files.

FedEx

Tax calculation

Configured Commerce uses the ITaxCalculator interface to calculate tax on orders. This interface implements the CalculateTax and PostTax methods.

public interface ITaxCalculator : IDependency
{
    /// <summary>The calculate tax.</summary>
    /// <param name="originAddress">The origin Address.</param>
    /// <param name="customerOrder">The customer order.</param>
    void CalculateTax(OriginAddress originAddress, CustomerOrder customerOrder);

    /// <summary>The post tax.</summary>
    /// <param name="originAddress">The origin Address.</param>
    /// <param name="customerOrder">The customer order.</param>
    void PostTax(OriginAddress originAddress, CustomerOrder customerOrder);
}

You can configure the tax calculator using the dependency name as the value of the TaxCalculator application settings. The default value is Standard.

TaxCalculator_PostTaxes (Boolean)

TaxCalculator_StorePickupShipCode (String)

TaxCalculator_StorePickupStateAbberviation (String)

TaxCalculator_StorePickupZipCode (String)

TaxCalculator_TaxCode1ForPercent (String)

Although each tax calculator has unique application settings, they all execute tax calculation on the checkout page.

Configured Commerce has the following tax calculation services:

Avalara

CyberSource

📘 Note If you use a custom tax calculator after calculating the tax, the customerOrder.TaxCalculated property must be set to true. If you set it to false, the storefront displays the tax as TBD on the Cart and Review and Checkout pages. Although Configured Commerce applies tax to the order, the storefront displays the incorrect amount.

Translation service

Multi-language is a capability in Configured Commerce with some basic integration configuration. You can build custom translation services using the ITranslationService interface.

public interface ITranslationService : IDependency
{
    /// <summary>Translate a string by auto-detecting the from language to the to
    /// language .</summary>
    /// <param name="toLanguageCode">Language Code to translate to.</param>
    /// <param name="stringsToTranslate">List of strings to translate.</param>
    /// <returns>Translated text.</returns>
    IList<string> TranslateText(string toLanguageCode, IList<string> stringsToTranslate);

    /// <summary>Translate a string from the from language to the to language.</summary>
    /// <param name="fromLanguageCode">Language Code to translate from.</param>
    /// <param name="toLanguageCode">Language Code to translate to.</param>
    /// <param name="stringsToTranslate">List of strings to translate.</param>
    /// <returns>Translated text.</returns>
    IList<string> TranslateText(string fromLanguageCode, string toLanguageCode, IList<string> stringsToTranslate);
}