Ektron 9.00

Configuring eCommerce

This section describes the configuration screens located in the Workarea at Settings > Commerce > Configuration and Settings > Commerce > Tax.

Countries

Configuring Countries

Use the Countries screen to modify existing country information or add new countries to eCommerce.

How countries are used

How Countries are Used

  • to define country tax tables—For example, assume Canada has a national tax of 5% that applies to the sale of certain goods. National tax tables are defined in the Country Tax Tables screen.
  • to determine shipping costs—In the checkout process, a purchaser selects a shipping address, which includes country. So, be sure to enable countries from which customers (site visitors) can enter orders. Countries are also part of the location on the Warehouse screen. An order’s shipping cost is determined by the distance between the warehouse and the destination.
Default countries

Default Countries

By default, Ektron provides information for countries on the ISO list of English country names and code elements (ISO 3166-1-alpha-2 code).

The following is provided for each country.

  • name
  • numeric ISO code
  • long alphabetical ISO code
  • short alphabetical ISO code

The countries screen lets you enter new countries, and edit information for provided countries.

Creating a country

Creating a Country

Prerequisite

The new country’s ISO codes.

To add a new country:

  1. From the Workarea, choose Settings > Commerce > Configuration > Countries.
  2. Click New > Country.
  3. Enter information in the following fields:
    • Name—Enter the country’s name.
    • Numeric ISO—Enter the country’s ISO 3166-1 3-digit numeric ISO code. See Also: ISO 3166-1 numeric
    • Enabled—Check this box if you want this country to be active. Only active countries can be selected on the Edit Billing Information screen, which appears during the Checkout procedure.
    • Long ISO—Enter the country’s ISO 3166-1 alpha-3, 3-letter country code. See Also: ISO 3166-1 alpha-3
    • Short ISO—Enter the country’s ISO 3166-1 alpha-2, 2-letter country code. See Also: ISO 3166-1 alpha-2
  4. Click Save.
Editing a country

Editing a Country

  1. Go to Workarea > Settings > Commerce > Configuration > Countries.
  2. Click the name of the country that you want to edit.
  3. Click Edit.
  4. Edit any of the fields, which are described in Creating a Country
Deleting a country

Deleting a Country

  1. Go to Workarea > Settings > Commerce > Configuration > Countries.
  2. Click the name of the country that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK. The country is deleted.
Regions

Configuring Regions

The Regions screen lets you define geographic regions within countries that your eCommerce site services. For example, in the United States of America, each state is a region.

Regions are used in the same way that countries are used. See Also: How Countries are Used By default, the Regions screen includes 50 United States of America, the District of Columbia, and 9 Canadian Provinces.

Creating a region

Creating a Region

Prerequisite

The region’s country is defined in the Countries screen

  1. Go to Workarea > Settings > Commerce > Configuration > Regions.
  2. Choose New > Region.
  3. Use the following information to complete the screen.
    • Name—Enter the region’s name.
    • Enabled—Check this box if you want this region to be active. Only active regions can be selected on the Edit Billing Information screen, which appears when customers enter billing information during the Checkout procedure.
    • Code—Enter an abbreviation for this region.
    • Country—Select this region’s country from the pull down list. If the country is not there, exit this screen, and create the country using the Countries screen.
    • Add another region to this country?—This field saves the effort of selecting a country when entering several regions for one country.

      To add more regions for this country, check this box and press Save. When you do, the screen refreshes, and the most recently selected country appears as the default.

  4. Click Save.
Editing a region

Editing a Region

  1. Go to Workarea > Settings > Commerce > Configuration > Regions.
  2. Click the name of the region that you want to edit.
  3. Click Edit.
  4. Edit any of the fields, which are described in Creating a Region
Deleting a region

Deleting a Region

  1. Go to Workarea > Settings > Commerce > Configuration > Regions.
  2. Click the name of the region that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK.
Currencies

Configuring Currencies

eCommerce supports all currencies. However, customers can choose only enabled currencies. The Currency screen lets you enable and edit information for installed currencies.

Installed currencies

Installed Currencies

By default, Ektron provides currencies on the ISO 4217 Current Currency & funds code list.

The following information is provided for each installed currency.

  • name
  • enabled (yes or no)
  • numeric ISO code
  • alpha ISO code
  • exchange rate
Enabling currencies

Enabling Currencies

When users are setting prices in the Workarea or site visitors are shopping, they can only choose enabled currencies. When you install Ektron, the following currencies are enabled.

To see which currencies (other than the default) are enabled, click Action > Edit Exchange Rates from the Currencies screen. Only non-default, enabled currencies appear.

WARNING! The Euro and Australian dollar are shipped with a default exchange rate. If you will support these currencies, you should update the rate to its current value before going live. See Also: Defining and Updating Exchange Rates

To enable any installed currency:

  1. From the Workarea, choose Settings > Commerce> Configuration > Currencies.
  2. Click the currency you want to enable. (Use the Search box to quickly find a currency.) The Edit Currency screen appears.
  3. Check the Enabled check box.
  4. Click Update.
—Image—

The default currency

The Default Currency

The default currency is the reference currency when setting the exchange rate on the Edit Currency screen. For example, if the default is US dollars, USD appears on the left of the exchange rate equation, as shown below.

—Image—

The default currency is also the default value in the Currency Selector server control, and on the Pricing tab of the View/Edit Catalog Entry screen. See Also: Server Control Reference

Viewing and changing the default currency

Viewing and Changing the Default Currency

When you install Ektron, the default currency is U.S. dollars, indicated by the Numeric ISO code 840. At that time, you can change this by editing the value for the web.config file’s ek_ecom_DefaultCurrencyId tag. You must enable the new default currency in the Workarea before changing it in the web.config file.

WARNING! After your eCommerce feature goes live, do not change the ek_ecom_DefaultCurrencyId value in web.config.

IMPORTANT: If you edit the siteroot/web.config file's ek_ecom_DefaultCurrencyId property, you must begin a manual crawl. See Also: Starting Crawls Manually You will only see the new default currency in search results when that crawl is complete.

How currencies are used in the CurrencySelect server control

How Currencies Are Used in the CurrencySelect Server Control

If your developer places a CurrencySelect server control on a page, a site visitor can use it to select any enabled currency. See Also: Server Control Reference

—Image—

After a currency is selected, the prices change to that currency. From that point on, the cart and order use the selected currency. See Also: Defining and Updating Exchange Rates

Defining and updating exchange rates

Defining and Updating Exchange Rates

The Edit Currency screen lets you define an exchange rate between the default and any other currency. A good website for finding exchange rates is http://www.xe.com.

—Image—

The exchange rate can dynamically adjust prices when the rate changes. See Also: Alternate Currency Pricing

You can update the exchange rates using:

  • the Ektron API
  • the Edit Exchange Rates screen

The following Ektron API supports calling an exchange rate service to update rates automatically: Ektron.Cms.Commerce.ExchangeRateApi. For more information, see the Ektron API documentation (http://reference.ektron.com/developer/).

The Edit Exchange Rates screen lets you update the exchange rate for enabled currencies:

  1. In the Workarea, go to Settings > Commerce > Configuration > Currencies.
  2. Choose Action > Edit Exchange Rates. The Edit Exchange Rates screen appears, showing enabled currencies and their exchange rates.
    —Image—

  3. Update rates as needed.
  4. Choose Action > Update.
Editing a currency

Editing a Currency

  1. Go to the Workarea > Settings > Commerce > Configuration > Currencies.
  2. Click the currency you want to edit.
  3. You can only edit the Name, Enabled, and Exchange Rate fields. The Numeric ISO Code and Alpha ISO Code are not editable and are determined by the currency selected.
    • Name—Enter the currency’s name.
    • Enabled—Check this box to enable this currency.
    • Exchange Rate—Enter the exchange rate between this currency and the default one.
  4. Click Update.
Deleting a currency

Deleting a Currency

  1. Go to the Workarea > Settings > Commerce > Configuration > Currencies.
  2. Check the box next to the currency that you want to delete.
  3. Choose Action > Delete Selected. A confirmation message appears.
  4. Click OK. The currency is deleted.
Payment options

Configuring Payment Options

The Payment Options screen lets you determine which options are available for your customers to pay for their purchases.

Both options can be enabled, but only one gateway can be enabled at a time.

PayPal payments work like checks in that they need to be settled. After an order is placed, the payment must be marked as “settled” for the workflow to proceed.

Using PayPal with Ektron eCommerce

Using PayPal with Ektron eCommerce

Customers can use PayPal to pay for purchases from either of 2 points in the checkout process

  • the shopping cart screen
  • the payment screen

IMPORTANT: PayPal requires you to place the Pay with PayPal option on both the shopping cart and payment screens.

If you access PayPal via the shopping cart screen, you follow these steps.

—Image—

Here is the sequence illustrated above.

  1. From the Cart screen, a site visitor clicks PayPal.
  2. The site visitor logs into his or her PayPal account.
  3. Account information populates the shipping and billing addresses.
  4. The site visitor can change addresses if needed. If the PayPal account address is used for the order, it is saved as part of the site visitor’s eCommerce account information.
  5. Shipping costs are added.
  6. The order is confirmed.
  7. Site visitor checks out via PayPal.

Alternatively, the site visitor can use the standard eCommerce checkout process, select PayPal on the payment screen, and complete the order using the PayPal payment screen. That sequence is illustrated below.

—Image—

PayPal documentation

PayPal Documentation

Use the following PayPal technical documentation resources when integrating PayPal into your eCommerce site: PayPal Express Checkout Integration Guide and Payflow ACH Payment Service Guide, located at PayPal: Development & Integration Guides.

Enabling PayPal support

Enabling PayPal Support

  1. Create a Sandbox Account. This step includes updating Ektron’s web.config file.
  2. Begin Using PayPal
  3. Enable PayPal in the Workarea
Create a sandbox account

Create a Sandbox Account

  1. Sign on to PayPal Sandbox.
  2. Sign up for an account.
  3. You receive an email confirmation that directs you to another page.
  4. Log in using the information you provided in Step 2.
  5. Under Test Accounts, click Create a preconfigured buyer or seller account.
    —Image—

  6. Create a buyer account. You will use this to test the customer experience.
  7. Change the password to one you can easily remember.
    —Image—

  8. Click Home > Test Accounts > Create a preconfigured buyer or seller account.
  9. Click Account Type Seller.
    —Image—

  10. Create a seller account. You will use this to test the merchant experience.
  11. Change the password to one you can easily remember.
  12. In the upper left corner of the screen, click API Credentials.
    —Image—

  13. Open your siteroot/web.config file.
  14. Copy the following values from the API Credentials screen into the web.config’s providers/paypal element. Save web.config.
    • API Username > PayPalUser
    • API Password > PayPalPwd
    • Signature > PayPalSignature

The following illustration shows the PayPal API Username copied into the web.config file’s PayPalUser property.

—Image—

Encrypting PayPal authentication values

Encrypting PayPal Authentication Values

Follow these steps to encrypt the following values in the web.config file’s providers/paypal element.

  • PayPalUser
  • PayPalPwd
  • PayPalSignature
  1. Open the siteroot/web.config file.
  2. Set the AuthValuesEncrypted element to true.
    —Image—

  3. Save and close web.config.
  4. Open C:\Program Files\Ektron\CMS400vxx\Utilities.
  5. Run EncryptEmailPassword.exe. The Encrypt Utility dialog appears.
    —Image—

  6. Enter the PayPal user name into the Text field.
  7. Click Encrypt. The screen displays encrypted text in the Encrypted field.
  8. Copy the encrypted text and paste it into the web.config file’s PayPalUser element value.
  9. Repeat Steps 6 through 8 for PayPalPwd and PayPalSignature.
Test the sandbox account

Test the Sandbox Account

  1. Sign into Workarea > eCommerce > Cart.
  2. Click the PayPal button.
  3. Enter the buyer account user name and password that you created in Create a Sandbox Account. You proceed to the Ektron Checkout screen.

After completing these steps, you have verified your PayPal buyer experience and are ready to begin using PayPal.

Begin using PayPal

Begin Using PayPal

  1. Sign on to PayPal.
  2. Create a new account.
  3. Follow the instructions to obtain API credentials.
  4. Copy the following values from the API Credentials screen into the web.config’s providers/paypal element. Save web.config.
    • API Username > PayPalUser
    • API Password > PayPalPwd
    • Signature > PayPalSignature
  5. If you want to encrypt these values, see Encrypting PayPal Authentication Values.
  6. Enable PayPal in the Workarea.
  7. If desired, customize the PayPal page on your website.
Enable PayPal in the Workarea

Enable PayPal in the Workarea

  1. From the Workarea, choose Settings > Commerce > Configuration > Payment Options.
  2. Click Action > Edit Payment options. The Edit Payment Options screen appears.
  3. Check PayPal.
  4. Click Save.
Customizing the PayPal page

Customizing the PayPal Page

If you are using Ektron’s sample site and PayPal is enabled, the login screen contains an Ektron logo for demonstration purposes.

You can replace the logo using the apiparamHDRIMG property of the <providers> add name=”PayPal” element in the web.config file.

To change the logo, change the referenced image.

To learn how to customize other aspects of the page, see PayPal’s “Express Checkout Integration Guide” section “PayPal Page Style.” The guide is located at PayPal: Development & Integration Guides.

When setting values in the web.config’s providers/add name=” PayPal” element, prefix any variable with apiparam. For example, to set the header background color, enter apiparamHDRBACKCOLOR=”FFF666”.

Payment gateways

Configuring Payment Gateways

A payment gateway provider is a pluggable component that is integrated into the Ektron eCommerce module. A payment provider handles eCommerce customer payments by using third-party payment gateways. Ektron eCommerce module accepts payments such as credit cards or checks. Then, it passes that information to a third-party service. The third-party service processes the payment and returns a transaction ID that is stored with the customer's order.

Your company needs to set up an account with a third party payment service before using the payment provider. Ektron provides 4 standard payment gateways: authorize.net, Payflow, Sage Pay and PayFlowWebsite Payments Pro along with manual. The manual gateway accepts credit cards. In this case, the merchant emails the credit card information to the credit card company. You can customize these providers or create your own using the extendable Payment Gateway Provider architecture. See Customizing the Payment Gateway Provider.

In addition, some payment gateways might support recurring payments, while others might not. Recurring payments let you create a payment that recurs at a given interval for a specified period of time. For example, you could create a payment for $9.99 that occurs on the first of every month for the next 12 months. This is something to consider if your site relies on a subscription service.

Ektron lets you edit information on any provided gateway as well as create a new one.

Processing credit card transactions via a gateway

Processing Credit Card Transactions via a Gateway

The following sequence explains typical processing of credit card transactions. (source: www.authorize.net)

  1. A customer purchases a product from your site and submits payment information.
  2. Ektron passes the information to your payment gateway.
  3. The payment gateway provider (PGP) receives secure transaction information and passes it via secure connection to the Merchant Bank’s Processor.
  4. The Merchant Bank’s Processor submits the transaction to the Credit Card Interchange (a network of financial entities that manage credit card transactions).
  5. The Credit Card Interchange sends the transaction to the customer’s Credit Card Issuer.
  6. The Credit Card Issuer approves or declines the transaction, based on the customer’s available funds. It then passes the transaction results and, if approved, the appropriate funds back through the Credit Card Interchange.
  7. The Credit Card Interchange relays the transaction results to the Merchant Bank’s Processor.
  8. The Merchant Bank’s Processor relays the transaction results to PGP.
  9. The PGP stores transaction results and sends them to the customer and/or the merchant. This communication process averages 3 seconds or less.
  10. The Credit Card Interchange passes the transaction’s funds from the Credit Card Issuer to the merchant’s bank account.
Processing check transactions via a gateway

Processing Check Transactions via a Gateway

The following sequence explains how a payment gateway processes checks. (source: www.authorize.net)

  1. Customer authorizes merchant to charge the customer's bank account for an amount.
  2. Order and payment information is securely transmitted via the Internet to the payment gateway.
  3. The transaction is accepted or rejected based on initial data validation and security criteria defined by the payment gateway.
  4. If accepted, the transaction is sent to the ACH Network for settlement.
  5. The ACH Network uses the transaction’s bank account information to determine the bank that holds the customer’s account (the RDFI).
  6. The ACH Network instructs the RDFI to charge or refund the customer’s account.
  7. The RDFI transfers funds from the customer’s account to the ACH Network. The RDFI also notifies the ACH Network of any returns (if funds could not be collected from the customer’s bank account) or charge backs (if a customer disputes a purchase).
  8. The ACH Network transfers funds for the transaction to the payment gateway’s bank.
  9. After a holding period, the payment gateway provider initiates a ACH transaction that deposits the funds into the merchant’s bank account.
Establishing a relationship with a payment gateway provider

Establishing a Relationship with a Payment Gateway Provider

You need to set up an account with a third-party payment service before using a payment provider. Each payment gateway provider accepts configuration parameters. For example, Authorize.NET requires a username and password, while PayFlow requires a Username, password, vendor, and partner.

In addition, some payment gateways do not support subscription payments. Consider this if your site relies on subscriptions. See Also: Creating a Subscription

The default gateway

The Default Gateway

The eCommerce checkout uses the default gateway only. Additional gateways are unused unless one is changed to the default.

You cannot delete the default gateway. If you want to delete it, you must first make another gateway the default.

To change the default gateway:

  1. Go to Settings > Commerce > Configuration > Payment Options.
  2. Click the Payment Gateways tab. The currently-defined default has a check in the Default column.
    —Image—

  3. Click the radio button next to the gateway you want to make the default.
  4. Choose Action > Mark as Default. A confirmation message appears.
  5. Click OK.
Adding a payment gateway

Adding a Payment Gateway

NOTE: To create a new payment gateway provider, see Customizing the Payment Gateway Provider.

  1. In Ektron, go to Settings > Commerce > Configuration > Payment Options.
  2. Choose New > Payment Gateway.
  3. Enter information or select options for the following fields:
    • Name—Enter the name of the gateway.
    • Default—Check this box if this is the default gateway. If you do, and another gateway is currently the default, it is replaced by this one.
    • User ID—Enter your User ID. This ID will identify your account with this gateway provider.
    • Password—Enter the password for your account with this gateway provider.
    • Expand Custom Values—If this gateway provider needs additional fields of information, enter those values into the Custom 1 and Custom 2 fields.
    • Credit Cards—Check if this payment gateway accepts credit cards.
    • Checks—Check if this payment gateway accepts checks.

The following sections explain how to set up standard Payment gateways.

NOTE: When setting up a payment gateway, you are asked to enter authentication codes, such as user name and password. To keep them safe, Ektron encrypts these values when saving them to the database.

Setting up a PayFlow payment gateway

Setting up a PayFlow Payment Gateway

NOTE: See PayFlow's website for additional instructions on setting up the PayFlow Gateway.

When setting up a PayFlow payment gateway:

  1. Set up an account with PayFlow. To do this, go to Paypal: Payflow Payment Gateway. During this process, you should obtain a Login ID and password.
  2. Go to Settings > Commerce > Configuration > Payment Options.
  3. Choose New > Payment Gateway.
  4. Enter information or select options for the following fields:
    • Name—Choose Payflow.
    • Default—Check this box to make PayFlow the default gateway.
    • User ID—Enter the user ID provided to you by the authorized PayPal Reseller who registered you for the Payflow SDK. If you purchased your account directly from PayPal, use PayPal.

      Limitations: 64 alphanumeric, case-sensitive characters.

    • Password—Enter the password you defined while registering for account.

      Limitations: 6- to-32 alphanumeric, case-sensitive characters

    • Expand Custom Values—Click this text to open the Custom 1 and Custom 2 fields.
      • Custom 1—Enter the merchant login ID sent to you when you registered the account.

        Limitations: 64 alphanumeric, case-sensitive characters.

      • Custom 2—Enter the Partner ID sent to you by the authorized PayPal Reseller who registered you for the Payflow SDK. If you purchased your account directly from PayPal, use PayPal.

        Limitations: 12 alphanumeric, case-sensitive characters.

    • Credit Cards—Check if this payment gateway accepts credit cards. You should verify that this payment gateway supports credit card payments.
    • Checks—Check if you will accept checks with this payment gateway. You should verify that this payment gateway supports check payments.
Setting up a PayFlowWebsite Payments Pro payment gateway

Setting up a PayFlowWebsite Payments Pro Payment Gateway

The PayFlowWebsite Payments Pro payment gateway is used in the United Kingdom and Australia.

  1. Set up an account with PayFlowWebsite Payments Pro. To do this, go to Paypal: Payflow Payment Gateway.
  2. In the Workarea, go to Settings > Commerce > Configuration > Payment Options.
  3. Choose New > Payment Gateway.
  4. Enter information or select options for the following fields:
    • Name—Choose PayFlowWebsite Payments Pro.
    • Default—Check this box to make PayFlow the default gateway. See Also: The Default Gateway
    • User ID—Enter the API username sent to you by the authorized PayPal Reseller who registered you for the Payflow SDK. For example, sellUK_1271963915_biz_api1.ektron.com. If you purchased your account directly from PayPal, use PayPal.

      Limitations: 64 alphanumeric, case-sensitive characters.

    • Password—Enter the API password you defined while registering for the account.For example,1234567891.

      Limitations: 6- to-32 alphanumeric, case-sensitive characters

    • Expand Custom Values—Click this text to open the Custom 1 and Custom 2 fields.
      • Custom 1—Enter the API signature sent to you by the authorized PayPal Reseller who registered you for the Payflow SDK. For example, AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
        Limitations: 64 alphanumeric, case-sensitive characters.
      • Custom 2—Not used
    • Credit Cards—Check if this payment gateway accepts credit cards. You should verify that this payment gateway supports credit card payments.

After defining the payment gateway, you typically want to test it. See Testing a Payment Gateway

Setting up an Authorize.Net payment gateway

Setting up an Authorize.Net Payment Gateway

  1. Set up an account with Authorize.Net. To do this, go to Authorize.Net . During this process, you should obtain a Login ID and password.
  2. In the Workarea, go to Settings > Commerce > Configuration > Payment Options.
  3. Choose New > Payment Gateway.
  4. Enter information or select options for the following fields:
    • Name—Choose Authorize.Net.
    • Default—Check this box to make Authorize.Net the default gateway.
    • User ID—Enter the Login ID you obtained in Step 1.
    • Password—Enter the password you obtained in Step 1.
    • Custom 1 and Custom 2—Not used.
    • Credit Cards—Check if you will accept credit cards with this payment gateway. You should verify that this payment gateway supports credit card payments.

This gateway accepts only credit cards. No checks.

After defining the payment gateway, you typically want to test it. SeeTesting a Payment Gateway

Setting up a SagePay payment gateway

Setting up a SagePay Payment Gateway

NOTE: SagePay does not support recurring billing nor check payments.

  1. Set up an account with SagePay. To do this, go to Sage Pay. During this process, you should obtain a Login ID and password.
  2. Set up a SagePay simulator account using Sage Pay Account Registration.
  3. From the Simulator Main Menu, click Account > Valid Currencies for this Account. Enable currencies set up in your Workarea’s Currencies screen. See Also: Configuring Currencies
  4. In Ektron, go to Settings > Commerce > Configuration > Payment Options.
  5. Choose New > Payment Gateway.
  6. Enter information or select options for the following fields:
    • Name—Choose SagePay.
    • Default—Check this box to make SagePay the default gateway.
    • User ID—Enter the User ID you obtained in Step 1.
    • Password, Custom 1, Custom 2—Not used.
    • Credit Cards—Check if this payment gateway accepts credit cards. You should verify that the gateway supports credit card payments.
    • Checks—Not available with SagePay.

After defining the payment gateway, you typically want to test it. SeeTesting a Payment Gateway and Testing SagePay Payment Gateway

Testing a payment gateway

Testing a Payment Gateway

Typically, you test a default payment gateway before going live with it. eCommerce provides a test mode for this purpose. While eCommerce is in test mode, customers cannot purchase goods. So, disable test mode before going live with a new default payment gateway.

To test a payment gateway, open the siteroot/web.config file and set <ektronCommerce> ek_ecom_TestMode to true.

<ektronCommerce>
   <add key="ek_ecom_ComplianceMode" value="false" />
   <!-- This is used only when compliance mode is on, and cannot be less than 4. -->
   <add key="ek_ecom_PasswordHistory" value="4" />
   <add key="ek_ecom_OrderProcessingDisabled" value="false" />
   <add key="ek_ecom_TestMode" value="true" />
    ....

When testing is done, change the value of ek_ecom_TestMode to false.

Testing SagePay payment gateway

Testing SagePay Payment Gateway

Do not use the following cards with the SagePay test card number when testing the SagePay payment gateway:

  • Japan Credit Bureau (JCB)
  • Mastercard
  • Visa Electron UK Debit
  • Visa Delta Debit
  • American Express

Because these cards do not have a cardholder field, the following error is displayed: The CardHolder field should be between 1 and 50 characters long.

To test the SagePay Payment Gateway:

  1. Follow instructions in Testing a Payment Gateway.
  2. Open your siteroot/web.config file.
  3. Set <EktronPaymentGateway>/<providers> SagePay SimulatorMode to true.
    <EktronPaymentGateway defaultProvider="Automatic"> 
  <providers> . . 
    <add name="SagePay" 
      type="Ektron.Cms.Commerce.Providers.Payment.SagePayGateway" 
      SagePayVersion="2.23" SimulatorMode="true" 
      Description="Ektron CMS Order" />
  </providers>
</EktronPaymentGateway>
  4. When testing is complete, change the value of SimulatorMode to false.
Editing a payment gateway

Editing a Payment Gateway

  1. Go to Workarea > Settings > Commerce > Configuration > Payment Options.
  2. Click the payment gateway that you want to edit.
  3. Click Edit.
  4. Edit any of the fields, which are described in Adding a Payment Gateway.
  5. Click Save.
Deleting a payment gateway

Deleting a Payment Gateway

NOTE: You cannot delete the default gateway. If you want to delete it, you must first make another gateway the default.

  1. From Workarea, choose Settings > Commerce > Configuration > Payment Options.
  2. Click the payment gateway that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK.
Check support

Check Support

Payment gateways generally offer 2 payment mechanisms: credit cards and checks. You can enable or disable check support for a gateway via the Settings > Commerce > Configuration > Payment options > Edit Payment Gateway screen.

If checks are enabled for the default payment gateway, a site visitor can pay by Check on the payment screen. If check support is not enabled, the Payment Method field does not appear.

Check support integration documentation

Check Support Integration Documentation

Use the following resources to familiarize yourself with integrating checks into your eCommerce site.

Effect of check payment on order processing

Effect of Check Payment on Order Processing

The following describes a typical sequence of events when processing a check for eCommerce payment.

However, Ektron is very flexible and does not enforce this sequence. For example, you can enter a tracking number and mark an order shipped even though its payment has not been captured yet.

  1. eCommerce user accesses the View Payment screen’s Capture option, which submits a payment request to the customer’s bank.
    —Image—

  2. A few days later, the funds are transferred to the merchant’s account.
  3. eCommerce user accesses the View Payment screen’s Mark as Settled option to confirm the receipt of funds.
    —Image—

  4. If goods are tangible, eCommerce user ships the merchandise, using the View Payment screen’s Enter Tracking Number option to insert the tracking number and confirm the shipment.
    —Image—

  5. If goods are not tangible, the workflow sends the customer an email with purchase details, such as how to download it.
Credit card types

Configuring Credit Card Types

Use this screen to enter types of credit cards that your eCommerce system may use. By default, Ektron’s sample sites provide the following card types.

  • American Express
  • Diners Club (not accepted by default)
  • Discover
  • MasterCard
  • Visa

You can edit the information provided for these types or enter a new one.

Where credit card types are used

Where Credit Card Types are Used

During the checkout process (managed by the Checkout server control), the Payment screen includes a drop-down list of enabled credit cards.

—Image—

Creating a credit card type

Creating a Credit Card Type

To create a new credit card within Ektron:

  1. From the Workarea, choose Settings > Commerce > Configuration > Card.
  2. Choose New > Card Type to see the Add Card Type screen.
  3. Enter the credit card's name in the Name field.
  4. Enable the Accepted check box if site visitors can use this card to make purchases on your website.
  5. Add an image for the credit card. The image must reside on your computer.The image does not appear on the standard checkout screen, but it is a field in the XML, so you can enable it using XSLT.
    1. Click Change. The Library Upload screen appears.
    2. Click Add Library.
    3. Click Browse and navigate to the folder that contains the image.
    4. Choose the image file.
    5. Enter a title in the Title field.
    6. Click Add Library. The file name appears in the Image field with the image directly below.
  6. Enter a Regex expression. See Also: Using RegEx Expressions for Validation
  7. Click Save.
Using regex expressions for validation

Using RegEx Expressions for Validation

A RegExregular expression; an alias that creates a pattern. For example, blogs.aspx?blogmonth=3&blogyear=2012&blogid=41 can be a RegEx blogs/2012/03/41. From that, a site visitor can infer blogs/2012/03/40 to see the previous post, or enter blogs/2012/03 to see all March 2012 posts expression is a simple way to validate a credit card account number. (See Also: http://regexlib.com/.) Validation occurs when a site visitor completes the Checkout procedure’s Submit Order screen

RegEx prevents the submission of invalid account numbers to a payment gateway, which may charge a fee for such failures.

Ektron provides a RegEx expression for the credit cards supplied with the medical sample site. You can modify them as needed. If you enter a new credit card, you can enter a RegEx expression for it.

Editing a credit card type

Editing a Credit Card Type

  1. From the Workarea, choose Settings > Commerce > Configuration > Card.
  2. Click the Credit Card Type that you want to edit.
  3. Click Edit.
  4. Edit any of the fields, which are described in Creating a Credit Card Type
  5. Click Save.
Deleting a credit card type

Deleting a Credit Card Type

  1. From the Workarea, choose Settings > Commerce > Configuration > Card.
  2. Click the Credit Card Type that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK. The Credit Card Type is deleted.
eCommerce shipping screens

Configuring eCommerce Shipping Screens

The eCommerce shipping screens let you specify information about where catalog entries are stocked, how they are packaged, and the available shipment methods.

Using a Warehouse

Using a Warehouse

Use the Warehouses screen to enter information about warehouses that stock your catalog entries. eCommerce uses this location as the “from” address when calculating shipping costs.

Only the default warehouse is used by the checkout process. Additional warehouses are unused until they are made the default. See Also: Changing the Default Warehouse

Prerequisite

Configuring Regions and Configuring Countries must be set up

Creating a warehouse

Creating a Warehouse

  1. Go to Settings > Commerce > Shipping > Warehouses.
  2. Choose New > Warehouse.
  3. Enter information or select options as follows:
    • Name—Enter the warehouse’s name.
    • Street1, Street2—Enter the warehouse’s street address
    • City—Enter the warehouse’s city.
    • Postal Code—Enter the warehouse’s postal code.
    • Country—Select the warehouse’s country from the pull-down list.
    • State/Province—Select the warehouse’s state or province from the pull-down list.
    • Default Warehouse—This check box indicates if this is the default warehouse.
  4. Click Save.
Changing the default warehouse

Changing the Default Warehouse

NOTE: You can also specify a warehouse as the default via the Edit Warehouse screen’s Mark Default Warehouse toolbar button ().

  1. Go to Workarea > Settings > Commerce > Shipping > Warehouses.
  2. Click the radio button next to the warehouse that you want to make the default.
  3. Choose Action > Mark Default Warehouse. A confirmation dialog appears.
  4. Click OK.
Editing a warehouse

Editing a Warehouse

  1. Go to Workarea > Settings > Commerce > Shipping > Warehouses.
  2. Click the warehouse that you want to edit.
  3. Click Edit.
  4. Edit any of the fields as described in Creating a Warehouse.
  5. Click Save.
Deleting a warehouse

Deleting a Warehouse

You cannot delete the default warehouse. However, you can designate another warehouse as the default, then delete the one that was the default.

  1. Go to Workarea > Settings > Commerce > Shipping > Warehouse.
  2. Click the warehouse that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK. The warehouse is deleted.
Packages

Configuring Packages

How packaging information is used

How Packaging Information Is Used

Each item in an order has size and weight dimensions. The shipping calculator uses them to fit the order into the smallest-sized and fewest packages. It then passes packaging information (number, sizes and weight) to the shipping provider, which returns the order’s shipping costs. If a catalog entry’s dimensions exceed all box sizes, eCommerce passes those dimensions to the shipping provider.

NOTE: Some shipping providers, FedEx and UPS for example, have size and weight limits on packages. If the size or weight exceeds the limit, shipping rates may not be returned when a site visitor is checking out. In this case, a site visitor cannot continue the checkout process and an application error is logged in the Event Viewer.

Size and weight units of measure

Size and Weight Units of Measure

By default, Ektron uses English units of measure (inches and pounds) for package size and weight. At the beginning of your eCommerce implementation, you can change to metric units of measure by updating the web.config file’s ek_measurementsystem tag value to metric.

WARNING! After your eCommerce feature goes live, do not change the web.config ek_measurementsystem value.

Creating a new package

Creating a New Package

  1. Go to Settings > Commerce > Shipping > Packages.
  2. Click New > Package.
  3. Enter package information in the following fields:
    • Name—Enter a text description of this package size.
    • Length—Enter the package’s length in the units of measure that appear to the right (inches or centimeters). See Also: Size and Weight Units of Measure
    • Height—Enter the package’s height in the units of measure that appear to the right (inches or centimeters).
    • Width—Enter the package’s width in the units of measure that appear to the right (inches or centimeters).
    • Max Weight—Enter the package’s weight in the units of measure that appear to the right (pounds or kilograms).
  4. Click Save.
Editing a package

Editing a Package

  1. Go to Workarea > Settings > Commerce > Shipping > Packages.
  2. Click the package that you want to edit.
  3. Click Edit.
  4. Edit any of the fields, which are described in Creating a New Package.
  5. Click Save.
Deleting a package

Deleting a Package

  1. From the Workarea, choose Settings > Commerce > Shipping > Packages.
  2. Click the package that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK. The package is deleted.
Shipping methods

Configuring Shipping Methods

Use the Shipping Methods to define choices your site visitors will have for delivering their purchases.

Prerequisites

  • Default warehouse with an address
  • A default shipping provider is defined in the siteroot\shipment.config file
Defining shipping providers

Defining Shipping Providers

When you instEktron, several providers exist in the siteroot\shipment.config file:

  • FedExShipmentProvider
  • FlatRateShipmentProvider
  • UPSShipmentProvider

However, the FedEx and UPS information is for testing purposes only. To use FedEx, UPS, or another shipping provider, obtain the following information from them. (The information can vary slightly for each provider.)

  • service URL
  • key
  • password
  • account number
  • meter number
  • transactionId

Then, enter that information into shipment.config, following the format of providers already in the file.

The shipment.config file also contains name and type properties for each provider. The specific text you insert is not important, but the name and type strings must match.

name="FedExShipmentProvider" 
  type="Ektron.Cms.Commerce.Shipment.Services.FedExShipmentProvider,
    Ektron.Cms.Commerce"

To define a custom shipping provider, see Customizing the Shipment Provider.

Defining the default shipping provider

Defining the Default Shipping Provider

While you can define any number of shipping providers in the shipment.config file, only one can be active. The active provider appears on the Settings > Commerce > Shipping > Methods > New > Shipping Method screen when you click View Options.

—Image—

Specify the default shipping provider via the defaultprovider property in siteroot\shipment.config.

<?xml version="1.0" encoding="utf-8" ?>
<shipmentProvider defaultProvider="FedExShipmentProvider">
  <providers>
    <add name="FedExShipmentProvider" ...
</shipmentProvider>
Adding a shipping model

Adding a Shipping Method

Use the Add Shipping Method screens to select shipping methods you will support. When a site visitor submits an order, these shipping choices appear on the Shipping screen.

  1. Go to Workarea > Settings > Commerce > Shipping > Methods.
  2. Choose New > Shipping Method. The Add Shipping Method screen appears.
  3. Enter information or make selections in the following fields.
    • Name—Enter the name of the shipping method. Site visitors select a shipping method for their order using this name
    • Active—Check this box if you want site visitors to be able to select this shipping method.
    • Provider Service—As explained in Defining the Default Shipping Provider, a default shipping provider is defined in your site’s shipment.config file. To view the methods offered by that provider, click View Options. Then, select from the drop-down list that appears.
  4. Click Save.
Editing a shipping method

Editing a Shipping Method

  1. Go to Workarea > Settings > Commerce > Shipping > Methods.
  2. Click the Shipping Method that you want to edit. The View Shipping Method screen appears.
  3. Click Edit ().
  4. Edit the fields described in Adding a Shipping Method.
Deleting a shipping method

Deleting a Shipping Method

  1. Go to Workarea > Settings > Commerce > Shipping > Methods.
  2. Click the Shipping Method that you want to edit.The View Shipping Method screen appears.
  3. Click Delete ().
Changing the order of the shipping method

Changing the Order of the Shipping Method

Each shipping method you define has an Order field. This determines the sequence in which shipping methods appear on the Shipping Rates screen when a site visitor is submitting an order.

The shipping method with 1 in the Order field appears at the top of the list.

By default, every shipping method’s order is set to 1. To set a sequence for shipping methods, follow these steps

  1. Go to Workarea > Settings > Commerce > Shipping > Methods.
  2. Choose Action > Reorder Items.
  3. Use the selection bar and arrows to arrange methods in the desired sequence.
    —Image—

  4. Choose Action > Save.
eCommerce tax screens

Configuring eCommerce Tax Screens

eCommerce provides a set of tax screens in the Workarea that lets you:

  • set up tax classes (for example, goods, services, tobacco)
  • define tax rates for these geographic entities (from most to least specific)
    • postal code
    • region
    • country
  • apply tax classes
    • for tax classes except shipping
    • applying shipping taxes
Applying tax classes to catalog entries

Applying Tax Classes to Catalog Entries

You assign a tax class (except shipping) to a catalog entry via its Properties tab’s Tax Class field (Content tab > select catalog entry > Action > Edit).

—Image—

Calculating an order's tax amount

Calculating an Order’s Tax Amount

During checkout, Ektron tries to find a tax rate for each catalog entry’s Tax Class and the shipping address’s geographic entity.

  1. Postal code
    1. If Ektron finds a tax rate for the postal code, it adds the amount. For example:
      • an item costs $100.00
      • the postal code tax rate = 5%
      • a tax of $5.00 is applied
    2. If Ektron does not find a tax rate for the postal code, it checks the shipping address for a regional tax code.
  2. Region
    1. If Ektron finds a tax rate for the region, it adds the amount. For example:
      • an item costs $100.00
      • the regional tax rate = 7%
      • a tax of $7.00 is applied
    2. If Ektron does not find a tax rate for the region, it checks the shipping address for a country tax code.
  3. Country
    1. If Ektron finds a tax rate for the country, it adds the amount. For example:
      • an item costs $100.00
      • the country tax rate = 10%
      • a tax of $10.00 is applied
    2. If Ektron does not find a tax rate for the country, then a tax is not added to the order.

If a postal zone has several taxes (for example, a local tax and a regional tax), build the combined percentage into the postal code tax. So, assume New York City has a 4% tax, and New York state has a 3% tax. Enter a combined total of 7% into postal zones within New York City. See Also: Cataloging Entries that Can Be Taxed

For example, the atrium chair is assigned to the Goods Tax Class. A person who lives in New York state purchases the chair. Although no postal tax class is defined for the shipping address, a regional tax of 8.5% is set up for New York state, and so is applied to the order.

—Image—

Calculating an order's shipping tax amount

Calculating an Order’s Shipping Tax Amount

The shipping tax is separate from the other taxes, and appears on a separate line of the order.

—Image—

A shipping tax is applied to an order if

  • shipping tax is enabled in web.config

    and

  • a tax rate is applied to one of the geographic regions in which the shipping address falls.

Unlike the other tax classes, you do not apply shipping tax to catalog entries. Instead, you apply them to geographic regions only. However, each tax class compares an order's shipping address against regional tax tables to calculate the tax.

Enabling the shipping tax within Ektron

Enabling the Shipping Tax within Ektron

To enable the shipping tax, open your siteroot/web.config file and change the value of the ek_ecom_ApplyTaxestoShipping element to True.

Enabling the shipping tax for a geographic region

Enabling the Shipping Tax for a Geographic Region

You apply a shipping tax to every applicable geographic region. As explained in Calculating an Order’s Tax Amount, the eCommerce module first looks for a tax applied to the order's postal code. If one is found, that shipping tax is applied. If none is found, eCommerce looks for a shipping tax applied to the order's region. If no regional shipping tax is found, eCommerce looks for a shipping tax applied to the order's country.

Applying a shipping tax to a geographic region

Applying a Shipping Tax to a Geographic Region

You apply a shipping tax rate to geographic regions as you do with the tax classes. See Also: Applying Local Taxes, Configuring Regional Tax Tables, Configuring Country Tax Tables

Cataloging entries that can be taxed

Cataloging Entries that Can Be Taxed

Use the Tax Class screen to define classes of catalog entries that can be taxed. When you install eCommerce, the following tax classes are installed.

  • alcohol
  • goods
  • service
  • tobacco
  • shipping

You can modify or delete all classes except shipping, which you can modify but not delete. You also can add new classes.

Creating a new tax class

Creating a New Tax Class

  1. Go to Settings > Commerce > Tax > Classes.
  2. Choose New > Tax Class.
  3. Enter the name of the tax class.
  4. Click Save.
Editing a tax class

Editing a Tax Class

  1. Go to Settings > Commerce > Tax > Classes.
  2. Click the Tax Class that you want to edit.
  3. Click Edit.
  4. Edit the name of the tax class.

  5. Click Save.

Deleting a tax class

Deleting a Tax Class

If a tax class has been assigned to a catalog entry that appears on any order, the Delete button does not appear.

  1. Go to Settings > Commerce > Tax > Classes.
  2. Click the Tax Class that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK. The Tax Class is deleted.
Applying local taxes

Applying Local Taxes

Use postal code tax tables to identify local areas (cities, counties, and so on) that apply taxes to eCommerce catalog entries. The areas are identified by their postal code. For example, London, England taxes alcohol delivered to addresses within it.

You only need to create a postal tax table if the area that applies the tax is smaller than a country’s geographical regions (states, provinces, and so on). If an entire region applies a tax, use a regional tax table.

Creating a new postal code tax table

Creating a New Postal Code Tax Table

Prerequisite

The postal code’s country and region are defined in the Regions and Countries screens

  1. Go to Settings > Commerce > Tax > Postal Tax Tables.
  2. Choose New > Postal Code.
  3. Enter information into the following fields:
    • Postal Code—Enter the postal code for which you want to enter a tax rate. If this is for a US state, the code must consist of 5 or 9 digits.
    • Region—Enter the geographic region (for example, state or province) in which the postal code resides.
    • Country—Enter the country in which the postal code resides.
  4. Select the Tax Rates tab and specify values for the tax rates, for example, Alcohol, Goods, Services, Shipping, Tobacco. For any tax class, enter a tax rate as a whole number. For example, if the tax is 7%, enter 7.
  5. Click Save.
Editing a postal code tax table

Editing a Postal Code Tax Table

  1. Go to Settings > Commerce > Tax > Postal Tax Tables.
  2. Click the ID of the tax table that you want to edit.
  3. Click Edit.
  4. Edit the fields described in Creating a New Postal Code Tax Table.
  5. Click Save.
Deleting a postal code tax table

Deleting a Postal Code Tax Table

  1. Go to Settings > Commerce > Tax > Postal Tax Tables.
  2. Click the ID of the tax table that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK. The postal code tax table is deleted.
Regional tax tables

Configuring Regional Tax Tables

Use regional tax tables to identify regions (states, provinces, and so on) that apply taxes to eCommerce catalog entries. For example, within the United States of America, the state of New Jersey applies a 5% tax on goods purchased on the internet and shipped to it.

You only need to define a regional tax table if the area that applies the tax is smaller than a country. If an entire country applies a tax, use a country tax table.

Editing a regional tax table

Editing a Regional Tax Table

A regional tax table is automatically created for every existing region. By default, tax rates are zero (0). To change any tax rate:

  1. Go to Settings > Commerce > Tax > Regional Tax Tables.
  2. Click on the name of the region for which you want to set tax rates. The View Region Tax Rate screen appears.
    —Image—

  3. Click Click here to edit the tax rates.
    —Image—

  4. Click Edit.
  5. Enter information into the following fields.
    • Name—Select the region for which you want to enter a tax rate.
    • Enabled—Enable or disable the regional tax entry as required.
  6. Select the Tax Rates tab and specify regional tax rates by class. For example, Alcohol, Goods, Services, Tobacco, and Shipping. For any tax class, enter a tax rate.
  7. Click Save.
Deleting a regional tax table

Deleting a Regional Tax Table

  1. Go to Settings> Commerce > Tax > Regional Tax Tables.
  2. Click the ID of the tax table that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK. The regional tax table is deleted.
Country tax tables

Configuring Country Tax Tables

Use country tax tables to identify nations that apply taxes to eCommerce catalog entries. For example, Ethiopia applies a 5% tax on goods purchased on the internet and shipped to it.

Editing a country tax table

Editing a Country Tax Table

A country tax table is automatically created for every existing country. By default, tax rates are zero (0). To change any country tax rate:

  1. Go to Workarea > Settings > Commerce > Tax > Country Tax Tables.
  2. Select the country for which you want to edit a tax table. The View Country Tax Rate screen appears.
  3. Click Click here to edit the tax rates.
  4. Click Edit.
  5. Select the Tax Rates tab and edit the tax rates, for example, Alcohol, Goods, Services, Tobacco, and Shipping. For any tax class, enter a tax rate.
  6. Click Save.
Deleting a country tax table

Deleting a Country Tax Table

  1. Go to Workarea > Settings > Commerce> Tax > Country Tax Tables.
  2. Click the ID of the tax table that you want to delete.
  3. Click Delete (). A confirmation message appears.
  4. Click OK. The country tax table is deleted.