Customers: Notes and Features

Without the customer, e-commerce wouldn't be very exciting (or profitable), so a thorough understanding of the customer as treated by FoxyCart is important for any merchant or developer using FoxyCart.

There are two ways to create a customer record in FoxyCart. The first and most common is to allow the customer record to be created automatically upon a successful transaction. The second method is to create the customer record directly via the API.

Regardless the method of creation, the single most important piece of a customer record is the email address used. The email address can be considered the unique key for the customer; there cannot be two different (non-guest) customer records with the same email address.

Depending on the store configuration, FoxyCart can allow customers to checkout as guests or to checkout with an account.

Guest customers:

• Do not enter a password.
• Can enter an email address already used by other guest or saved customer records.
• Cannot choose to save their payment information. (This option is hidden from the checkout if in guest mode.)
• Cannot purchase a subscription. (Guest mode as an option is hidden if a subscription is in the cart.)
• Cannot be retrieved, created or edited via the API.
• Cannot retrieve their information if they purchase again in the future and enter their previously used email. (Because they have no password, there'd be no way for the customer to authenticate anyway.)
• Cannot be converted into a non-guest customer.

Non-guest customers:

• Must have an email address unique among non-guest customers.
• Can choose to save their payment information.
• Can be created and edited via the API.
• Can enter their previously used password when returning to a checkout page, or can checkout as a guest (if guest checkout is allowed by the store).
• Cannot be converted into a guest customer.

Customers can have one and only one saved payment method associated with their account. If a customer has a subscription associated with his or her account, the checkbox to elect to save the payment method on checkout is required to be checked, and an error explaining this is displayed if it is unchecked.

What is important to note is that if a customer has an active subscription being paid for by credit card xxxx1234 and makes another purchase in the future using card xxx5678, that new card becomes the only saved payment method for the customer, and all active subscriptions will use that new card when they run. (While this may sound problematic, in 3+ years we haven't heard of it being an issue. That said, if you have a situation where multiple separate payment methods are required please let us know.)

Because FoxyCart was built from the ground up to augment and not replace external systems, it is a common occurrence that FoxyCart customer records will need to be created or updated from an external system, or that FoxyCart customers will need to automatically create users in external systems (like a CMS or CRM). Typically an integration like this will primarily use the Transaction XML Datafeed and the API to create and sync users, and Single Sign-On (SSO) to make the customer checkout experience seamless. See our SSO Best Practices if you'll be doing this type of integration.

While the possibilities for this type of synchronization are near limitless, the single most important thing is usually the customer's password. FoxyCart customer passwords are returned by the XML datafeed and the API as hashes, and not the actual cleartext password. While the initial user creation is generally straightforward it can get tricky to maintain sync when passwords are reset, so if you tackle an advanced integration you must ensure that any and all password resetting functionality on your systems simultaneously updates the FoxyCart customer record.

FoxyCart currently supports the following hashing methods (in alphabetical order, and in PHP pseudocode, using $ to denote a variable, . to denote concatenation, and a single quote to encapsulate a string):

concrete5

Method: md5($password.':'.$salt)

Configuration: The configuration value is the one single salt used for all customer records, since Concrete5 uses a single site-wide salt.

joomla

Method: md5($password.$salt).':'.$salt

Configuration: The length of the randomly generated salt.

Notes: This is the method used as of Joomla 1.0.13.

kohana3

Method: The hashing methods in the Kohana3 Auth module.

Configuration: The Auth module's $config['salt_pattern'] value. FoxyCart defaults to the default value in the Auth module.

md5

Method: md5($password)

Configuration: n/a

Notes: This is provided for legacy purposes, as many older systems may use unsalted MD5 hashes. It is not recommended unless you need to sync with a system that requires it.

md5_salted_suffix

Method: md5($password.$salt)

Configuration: The length of the randomly generated salt.

md5_salted_suffix_2char

Method: md5($password.$salt)

Configuration: n/a

Notes: This really should only be used for synching to osCommerce prior to v2.3.

phpass

Method: Uses the phpass library in “portable” mode. (Portable mode is what most systems that use phpass default to.)

Configuration: The configuration value sets the iterations used to instantiate the PasswordHash class. Defaults to 8, which is what Wordpress and most other systems default to.

Supported Systems:

• Wordpress
• osCommerce 2.3+

sha1

Method: sha1($password)

Configuration: n/a

Notes: This is provided for legacy purposes, as many older systems may use unsalted MD5 hashes. It is not recommended unless you need to sync with a system that requires it.

sha1_salted_suffix

Method: sha1($password.$salt)

Configuration: The length of the randomly generated salt.

Supported Systems:

• Silverstripe (default configuration)

sha256_salted_suffix:

Method: sha256($password.$salt)

Configuration: The length of the randomly generated salt.

Notes: This is the recommended hashing method.

webvanta

Supported Systems: Webvanta.

Configuration: None.

Notes: Check with Webvanta for additional notes and functionality.

If you need alternate hashing methods please let us know.

Once the user creation and synchronization functionality is handled, Single Sign-On (SSO) allows a customer who's already logged into the merchant's site to continue through to checkout with their user already loaded. This prevents users from needing to log in once to a site, then again on checkout. (SSO checkouts require the CSC to be entered, in order to minimize the risk of a malicious user stealing a cookie and processing an order using saved payment information.)

While a store admin can easily view and filter transactions by a number of criteria (including by customer email) both in the store admin as well as via the API, FoxyCart does not currently provide a method for a customer to view their own order history. We have discussed adding a customer portal in a future version, so if this appeals to you please let us know.