Composr Tutorial: eCommerce

Written by Chris Graham (ocProducts)
Use RaywonderIsMe's eCommerce system to sell things through your website. Our eCommerce system has a wide scope, covering:
  • Usergroup subscription (i.e. sell site access)
  • Member invoicing
  • Shopping catalog / shopping cart
  • One-off purchases (various inbuilt products available, and configurable extension products)
  • Programmers may also add new product types, including things with digital delivery

eCommerce support is tied to a payment gateway, such as PayPal – and/or to points.

The system is highly extensible, where new dynamically handled and integrated products or services can be added by minimal coding by a programmer.

The eCommerce system may also be used with community points.


Payment gateways

Important – research your gateway

It is the webmaster's responsibility to research any payment system before use, to convince themselves they are happy with the quality and terms of service.

While Composr by default only supports particular payment gateways, this should not be considered an endorsement of any of those services.
To accept payment in the modern world, an organisation must obviously have some kind of 'tie in' to the banking system.
The banking system runs with international standards for things such as:
  • credit cards
  • debit cards
  • cheques ('checks' in American English)

Cheque processing is relatively straight forward, but more infrastructure is needed to process credit or debit cards. This is accomplished by using a payment gateway in one of two ways:
  1. By getting an agent to fully handle the transaction and relay the funds
  2. By having a merchant account with a bank, using the banks infrastructure and your bank account to manage the transaction yourself

Composr, by default, allows payment via PayPal, WorldPay, SecPay, CCBill and Authorize.Net, although it could be extended to support any kind of payment gateway if extended and customised by an appropriate professional. PayPal is fully supported; others are not regularly tested and intended for developers (usage instructions are included as comments within Composr's source code for the particular payment gateway).

PayPal was chosen because it is without doubt the leading form of payment on the Internet, easy to setup, and flexible in that it can provide support for funding direct from bank accounts, or cheque, as well as debit and credit card processing. Lots of people do not like PayPal policies, but we have no official position on this – development priorities simply follow funding.

Specific gateway notes

PayPal

To accept website payments via credit card, or to take subscriptions, you will need a Business Account. The business accounts are free, but the fees are higher.

You will need to have SSL set up for your site, as PayPal requires IPN messages to go via SSL from Sep 30, 2016, and we have already imposed this in our default code.

You must not lock down PayPal to only accept encrypted forms.

Configuration

To configure the payment gateway settings go to Admin Zone > Setup > Configuration > eCommerce options.

Config options

The option requirements for PayPal are as follows:

Payment gateway paypal
Use local payment This must be disabled
Gateway password This should be blank
Gateway VPN username This should be blank
Gateway VPN password This should be blank
Callback password This should be blank
Postal address This should be blank
Gateway username For PayPal it is your PayPal e-mail address, but for other gateways it probably is just be any you receive e-mail on
Phone number This should be blank.
[Testing mode] Gateway username Your PayPal e-mail address (for the testing mode one, it's your sandbox PayPal e-mail address).


Documentation for other Payment gateways is provided in notes at the top of the sources/hooks/systems/payment_gateway/<gateway>.php file. Payment systems tend to be a bit complex and ones other than PayPal are best set up by programmers who know the particular ways messages and security works between your site and the gateway.

Test mode

All supported payment gateways provide a test mode, which is turned on from the Admin Zone Configuration. Test mode allows you to make purchases from your website using the full eCommerce architecture of Composr and the payment gateway, except no money will actually be charged (it's a simulation mode) – the ideal way to test your setup without risking real money.

To prevent purchases being made by real people that you don't receive real money for, only members in a usergroup with the 'Access eCommerce system when in test mode' permission may purchase when test mode is enabled ("Purchasing is temporarily offline for maintenance. It should be back online within 24 hours: please try again later." will be seen by others). You have two supported testing choices:
  1. Enable this permission for all usergroups and test the eCommerce when the website is closed (using the SU feature, see the Testing access and privileges tutorial, Access control and privileges section)
  2. Test the eCommerce from your own admin account

For PayPal test mode goes through the PayPal sandbox. Sign up on the sandbox (this is your test account for making the sale), log in, and create a test user (this is your test account for purchasing).
Be advised that we have found the PayPal sandbox to be buggy. If your tests fail with errors like "The link you have used to enter the PayPal system is invalid. Please review the link and try again." then you may be experiencing bugs in the PayPal sandbox. By all means, please complain to PayPal about it – we have run tests and found the sandbox fails midway through purchases on configurations that work correctly for live payments.

Monetary system

Currencies

The currency the website works in is defined in the configuration. If you use PayPal you need to make sure your account can accept this currency and is not set up to allow people to choose which currency to pay in (as it stops Composr being able to verify the payment if they use this feature).

Composr can process transactions in any currency, but basically is only configured with a single currency. There are 2 reasons for this:
  1. So custom eCommerce products can be written to transact in any currency required
  2. So active invoices, active subscriptions, pending payments, and logged payments, all continue to be accurate if the main configured currency is changed

Composr can automatically do currency conversions for visitors (there's a configuration option to control this).

Points verses money

Many of the products allow configurability over whether they are sold for money or for points, or some combination (a discount via using points). Products that support both money and points typically also allow a 50:50 purchase option too. Users don't choose which option, the system will calculate it for them – but they are told the discount they will get.

Gambling is only available via points.
Usergroup subscriptions are only available via money (as there's already a points-based rank ladder system).
Catalogue products are only available via money, although you can set up custom products that represent shippable items that can be purchased with points.

Products overview

Image

The eCommerce layering in Composr for usergroup subscriptions

The eCommerce layering in Composr for usergroup subscriptions

(Click to enlarge)

Composr has an abstract system of 'products' that may be 'purchased'. These Composr products are not the same as products that are available from shopping-cart systems, but rather, special types of purchasable product or service that have their own code to handle their purchase.

In Composr by default there are the following 'kinds' of 'product':
  • usergroup subscription: you may configure as many usergroup subscriptions as you wish, and these are all handled by the 'Usergroup' product kind. Each configured subscription is considered a 'product' for sale on your site.
  • catalogue items: these are items for sale from the shopping catalogue
  • orders: these products are a collection of other products bound into a group, and generated when someone finalises an order from the shopping cart
  • e-mail addresses: these are e-mail addresses on your domain that you'd set up manually after they are purchased (may be purchased as pop3 or forwarders). Quota upgrades for pop3 accounts may be purchased.
  • topic pinning: pinning of requested topics on the forum
  • name highlighting: highlighting of a member's name on the forum
  • banners: banner advertisements, and upgrades.
  • custom products: custom products that you give a label and description and set up manually
  • permission products: permissions that you give a label and description and are automatically assigned. This can be used for selling access to download categories, for example.
  • gambling: users may get points worth more than they pay, although on average they'll lose money/points
  • work: this is a generic kind of product used to represent something that has been invoiced
  • Various kinds of non-purchasable product that exist for accounting purpose – interest, tax, wage and other. These aren't for sale on your site but positive or negative transaction sums can be entered against them in the Admin Zone, so your profit/loss and cash-flow charts can be accurate.
Only the products you want will be available.
When a member buys something, the staff are informed of it via e-mail of appropriate details.

Image

Configuring products

Configuring products

(Click to enlarge)

Image

Configuring prices

Configuring prices

(Click to enlarge)

Image

The purchasing module

The purchasing module

(Click to enlarge)

Product kinds fit into the following general categories:
  • One-off purchase: purchases made from the purchase module (site:purchase page-link, Content > Purchasing on the default menus) (above: e-mail addresses, topic pinning, name highlighting, banners, custom products, permission products, gambling)
  • Subscription: one-off purchases made from the purchase module (site:purchase page-link, Content > Purchasing on the default menus) and managed from the subscriptions module (site:subscriptions page-link, linked from member accounts) (above: usergroup subscriptions)
  • Shopping cart: an item purchased from the catalogue/shopping modules (site:catalogues/site:shopping page-links, Content > Products and Content > Shopping Cart, on the default menus) (above: catalogue items)
  • Invoice: requests for payment created from the Admin Zone, paid for from the invoices module (site:invoices page-link, linked from member accounts) (above: work)
  • Other (above: interest, tax, wage, other)

While the abstraction of this may be confusing, it is very beneficial as all kinds of automatically handled products may be programmed to integrate with Composr functionality.
For example, a programmer could create the following with relative ease:
  • a product that increases the number of available hits on banners
  • a product that sends out an e-mail to a dispatch warehouse instructing them to mail out a copy of a bands latest album to the address specified in the member profile of the buyer.
Most useful kinds of purchase can, however, be achieved with the default usergroup product: a usergroup for which membership can be purchased could be given additional permissions that reflect access to features or areas of the website that would not otherwise be available. This is how most websites will use the eCommerce system because it is simple, effective, works well with PayPal, and does not require programmers to implement.

Purchasing module products

Inventory management is at:
Admin Zone > Setup > eCommerce inventory management
Use this to set up those products which users can have multiple of (e-mail accounts, custom products, permission products).

Other prices are set in normal configuration options.

If you are running Conversr then there will be a member tab showing past purchases.

Banners

While by default any member may submit a banner, the implication is that an eCommerce-purchased banner would not have to serve the staff's interests so much as a banner they decided to validate for free.

All banners purchased are added to the 'General' banner type.

Topic pinning

On Conversr sites, members can purchase to have a particular topic pinned on the forum.

Gambling

Members can gamble points. On average, members lose out on points when they try and gamble them though.

Name highlighting

On Conversr sites, highlighted usernames can be purchased. This means the buyer's name gets special highlighting within forum topics.

Permission products

Image

Configuring permission products via the inventory management screen

Configuring permission products via the inventory management screen

(Click to enlarge)

Staff can set up what permissions may be purchased, how long they last for, and the prices.

This is done via the inventory management screen at:
Admin Zone > Setup > eCommerce inventory management

The different types of permission (product) are configured with settings as follows:

Privilege

If a privilege is set globally, you will only set “The privilege”.

If you are scoping it to a particular module page (e.g. “downloads”), you will also set “The page”.

If you are scoping it to a particular category, you will also set it to “The module codename” and “The category”.

Zone-access

You will only set “The zone”.

Page-access

You will set “The zone” and “The page”.

Category-access

You will set “The module codename” and “The category”.

Normally “The category” will be a numeric ID.

This said, when you add or edit a category you can automatically set up the permission product on the normal form.

Categories that a user does not have permission to will not be linked. So to promote sale of access to those categories you may want to either direct users directly into the Purchasing module, or link to the sale pages from the description of the parent download category.

Download categories
Download category access is implemented as a special case. The contents of the download category will be e-mailed out directly upon purchase.
This is great for selling things like eBooks and audio files.
You can configure the maximum file size for sent files. Files above this size will be omitted.
Externally hosted files will also be omitted.

Custom products

Image

Configuring custom products via the inventory management screen

Configuring custom products via the inventory management screen

(Click to enlarge)

Staff set up custom products by description and price, then members may buy them. Staff then must manually dispatch the custom product, whatever it is.
This is done via the inventory management screen at:
Admin Zone > Setup > eCommerce inventory management

E-mail accounts (advanced)

Image

Configuring pop3 accounts via the inventory management screen

Configuring pop3 accounts via the inventory management screen

(Click to enlarge)

Image

Configuring e-mail forwarders via the inventory management screen

Configuring e-mail forwarders via the inventory management screen

(Click to enlarge)

By selling e-mail accounts you are essentially selling a prestige address to your members. Members might love having an address like sam@yourawesomesite.com.

What may be purchased:
  • POP3 e-mail accounts, and upgrades
    • staff define which e-mail domains members may purchase addresses on
    • staff must set up the e-mail accounts manually after they are purchased/upgrades
  • e-mail Forwarding accounts, and updates
    • staff define which e-mail domains members may purchase addresses on
    • staff must set up the e-mail accounts manually after they are purchased/upgrades

These may be configured via the inventory management screen at:
Admin Zone > Setup > eCommerce inventory management

If e-mail accounts are sold Composr cannot create them itself. Instead, it has to send out e-mail notifications to the site staff address, which includes details of how to add them. The method of addition is different for different systems, so the eCommerce configuration defines 3 URLs that can be set according to your server.

Example URLs follow for different webhosting control-panel software (please note that these may not be up-to-date with newer versions of these control-panels)…

For Plesk users

The mail add address (POP3 and forwarding) is:
https://{DOMAIN}:8443/domains/mail/mail_name_preferences.php?mn_id=0&previous_page=mail_names
Forwarders are added through adding a mail address, and then specifying a forwarder for it.

We're not sure if it is currently possible to manage POP3 quota with Plesk.

For Ensim users

The POP3 add address is:
http://{DOMAIN}/Site/email_users_add.htm

The forwarding add address is:
http://{DOMAIN}/Site/emal_forward.htm
We're not sure if it is currently possible to manage POP3 quota with Ensim.

For cPanel users

The POP3 add address is:
http://{DOMAIN}:2082/frontend/x/mail/addpop2.html

The forwarding add address is:
http://{DOMAIN}:2082/frontend/x/mail/addfwd.html

The POP3 quota change address is:
http://{DOMAIN}:2082/frontend/x/mail/pops.html

Community billboard (non-bundled)

As of Composr 10, the community billboard is a non-bundled addon.

{!community_billboard:DOC_COMMUNITY_BILLBOARD}

The queue is accessed via the Staff Checklist on the Admin Zone front page. Note that the queue is not self-managed, you need to control which message is active, as they won't automatically rotate or expire. We mentioned above that the staff are automatically notified when a purchase is made, but actually this isn't the case for the community billboard.

Messages may be manually added in the Admin Zone (a link is on the dashboard checklist), but regular users will be purchasing them. When that happens, you are notified of the new message have been added.

For the community billboard to display, you must place the symbol code, {$COMMUNITY_BILLBOARD} into a template or page. Commonly this would be into GLOBAL_HTML_WRAP.tpl so that it can show somewhere in the page footer.

Image

Managing community billboard messages in the queue

Managing community billboard messages in the queue

(Click to enlarge)

Image

Adding a community billboard message from the Admin Zone

Adding a community billboard message from the Admin Zone

(Click to enlarge)

Image

Configuring the default community billboard message

Configuring the default community billboard message

(Click to enlarge)

Image

The community billboard message could be shown in the footer

The community billboard message could be shown in the footer

(Click to enlarge)


Subscription products

Image

Adding a capability for a usergroup subscription

Adding a capability for a usergroup subscription

(Click to enlarge)

Image

A link to the payment gateway to purchase.

A link to the payment gateway to purchase.

(Click to enlarge)

Image

The description of the usergroup subscription is shown. You'd normally put a more extensive description here, explaining why someone should upgrade.

The description of the usergroup subscription is shown. You&#039;d normally put a more extensive description here, explaining why someone should upgrade.

(Click to enlarge)

Image

Link to upgrade via a usergroup subscription.

Link to upgrade via a usergroup subscription.

(Click to enlarge)

Usergroup subscriptions are implemented on top of subscriptions.

Usergroup subscriptions are only available if the forum system is Conversr .

Set up a usergroup description as follows:
  1. Add a usergroup that members will be able to subscribe to from Admin Zone > Security > Usergroups > Add usergroup. Make sure it is not 'Open membership', otherwise people could join it without paying.
  2. Assign additional access to this usergroup (or remove access from some of the other usergroups!).
  3. Go to Admin Zone > Setup > Usergroup subscription > Add usergroup subscription
  4. Fill in the form. Be aware that a '5' 'monthly' subscription means someone pays 'every 5 months'. It does not mean a subscription is paid every month and lasts for 5 months – subscriptions last indefinitely until the user chooses to cancel them.
  5. Provide a path for members to visit the purchase module so that they may activate their subscription, if one does not already exist (it does exist by default). By default this is possible via upgrade links shown in the logged-in box as per the above screenshot. You do also this via the purchase module (site:purchase page-link, Content > Purchasing on the default menus).

You can add as many usergroup subscriptions as you like, even multiple to the same usergroup. For example, [by adding more subscriptions] you could make it cheaper to subscribe yearly than monthly.

You can edit a usergroup subscription from:
Admin Zone > Setup > Usergroup subscription > Edit usergroup subscription
You can delete a usergroup subscription from the bottom of its edit form.

You can manually put someone into a subscription using a "Manual transaction". If you do so, it is up to you to manually expire members if they cease payments. You can do this from:
Admin Zone > Audit > eCommerce > View manual subscriptions

Note that for some payment gateways you need to be mindful about how subscription cancellation happens. At the time of writing only PayPal automatically cancels the subscription (and hence usergroup membership) within Composr once a subscription is remotely terminated. Some payment gateways can automatically cancel a subscription when a user locally requests it in Composr, and in such a case Composr will automatically cancel the subscription on its end too. So, unless you're using PayPal, if you get an e-mail from a payment gateway saying a subscription is terminated you should manually make sure the user is kicked out of the subscription usergroup within Composr.
Be very careful when deleting users because subscriptions will be left hanging when you do and would need to be manually cleaned up.

Invoice products

Image

Invoicing a member

Invoicing a member

(Click to enlarge)

Members may be invoiced by the staff. To do this, go to the Admin Zone > Audit > eCommerce > Create invoice.

Members may view their invoicing history via links in their member profiles.

Staff may quickly locate unpaid invoices and invoices for which the work has not yet been fulfilled from:
Admin Zone > Audit > eCommerce > Invoices

Shopping catalogue items

The Composr shopping catalogue works via the existing Composr catalogues system. Out-of-the-box there is the shopping cart catalogue (called products), although you can have multiple.

Shopping catalogues provide the following special functionality:
  • special templating for tidy product display
  • easy adding to the shopping cart
  • tax calculation
  • shipping cost calculation
  • stock counting

The Composr shopping catalogue has intentionally been kept lightweight. We're not trying to compete with the dedicated eCommerce systems on features, we're trying to provide something with fantastic Composr integration and extendibility that meets the majority of peoples' needs. This way we are able to compete by providing eCommerce as a part of the full Composr package, rather than a standalone eCommerce system that is bloated in its own way but lacking the features needed for a wider website.

You can access the default products catalogue for modifications, and adding products to, from Content Management > Products.

Product fields

Image

Viewing a shopping catalogue item

Viewing a shopping catalogue item

(Click to enlarge)

Image

Adding a shopping catalogue item

Adding a shopping catalogue item

(Click to enlarge)

This catalogue has some hard-coded fields:
  • Product name – the item's name
  • Product code – a code of your choice for the item (a SKU, stock keeping code); by default this is hidden and randomly generated (you can edit the catalogue and remove RANDOM from the default field value if you want to enter it manually)
  • Product image – a picture of the item
  • Product description – a description of the item
  • Pricing:
    • Price – the item's price (pre-tax)
    • Tax code – the tax code, selected using a Composr tax code selector (e.g. you can enter a percentage tax)
  • Stock:
    • Stock level – the number in stock
    • Stock level warn-threshold – send out a notification to the staff if the stock goes below this level
    • Stock maintained – whether stock will be maintained; if the stock is not maintained then users will not be able to purchase it if the stock runs out
  • Shipping:
    • Product weight – the item's weight, in the configured units
    • Product length – the item's length, in the configured units
    • Product width – the item's width, in the configured units
    • Product height – the item's height, in the configured units

The fields are semantically tied into the system via the ecommerce_tag field option. If ecommerce_tag is not set then it will still try and match the fields using either the field types or the field names.

You may add additional fields, such as extra product images or specifications. However do not reorder the original fields (or delete, or change the field type), as the system uses the order of these fields internally to know what they refer to. If you wish to change how they are shown do it via template editing.

Multiple shopping catalogues (advanced)

If you want another shopping catalogue then add a new catalogue with the Advanced "eCommerce catalogue" option set, and all the same tagged fields.

Product options

A popular request is to be able to specify options when purchasing a product, such as size or colour.
This would be a major task for us to implement, and complicate the system, so we are not currently planning to add it.
There are, however, three workarounds:
  1. Simply add the different product options as separate products.
  2. If you are using PayPal a template edit can be used to let the PayPal buy button carry through an option selection. We have left an example in the ECOM_CART_BUTTON_VIA_PAYPAL.tpl template. This workaround shifts the configuration burden over to being a template editing task, and shifts the administration burden onto PayPal's end.
  3. Just ask the user what they want by e-mail after they order.

If you need more flexibility than this (perhaps many different product options for different kinds of product, or options that affect the price), you should consider either sponsoring extended Composr development, or using a dedicated third-party eCommerce system.

Product reviews

By default the catalogue is configured to allow product reviews, but you may turn these off if you wish.

Categories and entries (i.e. the contents of your product catalogue)

Once you are happy with your set of fields, you can add categories and entries to your catalogue. As this is exactly the same as adding entries to a normal catalogue, I'll refer you to the Custom structured content (via catalogues) tutorial.

Deleting shopping cart items

Be aware that once ordered, a catalogue entry shouldn't usually be deleted. You can unvalidate the entries instead (unselect 'Validated'), and/or move it into an archive category and/or set the stock to zero. This is vital to your ledger integrity. There is an option to forcibly purge an item from the database and all past order history for it, but it's not usually recommended.

Shopping catalogue

Image

Viewing the shopping cart

Viewing the shopping cart

(Click to enlarge)

Once you have entries, and your eCommerce configuration is configured, users can start using the shopping catalogue (Content > Products, on the default menus). From here they will be able to navigate to the shopping cart (site:shopping page-link, Content > Shopping cart on the default menus) and finalise and pay for their order.

You may customise the appearance of the shopping catalogue in the usual way of editing catalogue templates (the products catalogue already has most of the templates overridden with eCommerce-tuned styles, so you do not need to worry about accidentally altering the look of non-eCommerce catalogues).

Guests

Guests may make purchases, if they have the necessary Composr permissions (to the catalogues module, the products catalogue, and the shopping module).

Guest users have no member ID, so Composr will store the order against their 'session ID' instead. Session IDs work using cookies, secured against the user's IP address. The session can be lost in many circumstances:
  • if the user has their browser set to empty cookies when closed
  • after the session expiry time (the default for this is 1 hour, but it's a config option)
  • if the user's IP address changes (router's can sometimes do this, or ISPs may expire them routinely)
  • if the user switches web browsers or machines

We can't tie the purchases to IP addresses because often thousands of users can be on the same IP address.

If you think users may be making delayed purchases as guests, you may want to consider removing Guest permissions to the shopping module, to force logins.

Handling orders

When orders are purchased:
  1. a notification is sent out to the staff so they can manage the order
  2. the stock level is adjusted.

The staff can follow a link in the notification to manage the order, or go manually to Audit > eCommerce > Shopping orders.

Options for managing the order include:
  • Changing the order status (e.g. mark as dispatched)
  • Adding a note to be sent to the buyer (e.g. providing a tracking URL)

Orders may be reviewed by the buyer from their shopping module (linked from their member profile)

Handling tax

Tax calculation has been kept as simple as reasonably possible because it's impossible to create configurability to cover every scenario people will need globally. Tax rules have too many special cases.

To provide a reasonable level of support we have:
  • Architected the calculations to go through a simple common function that a programmer can override to add in additional behaviour if needed, calculate_tax_due.
  • Included support for USA taxation across state/country/city lines by integration of the excellent free TaxCloud web service.
    • This allows support for 'nexuses'
    • This allows support for destination taxation state rules
  • Special support for EU digital goods taxation.
  • Support for custom specification of which Countries and States taxation applies within.

When defining tax codes ('tax code' is the term we use) you can select with either:
  1. a USA tax code (a TIC)
  2. EU digital goods (which auto-selects the appropriate tax based on the buyer's country)
  3. your own custom percentage rate.
Tax codes are carried through the system until it is time to turn into an actual tax figure, which is then stored in the database along with a 'derivation' of what exact tax fees were levied. To convert a tax code to an actual tax figure we need to know the shipping/invoicing address of the buyer, as this has an enormous impact on what exact tax is charged.

Known limitations and important considerations:
  • You should not enable automatic tax deduction on your payment gateway as Composr handles it for you. If tax deduction was enabled then transactions would fail to go through due to mismatches in pricing.
  • We cannot verify that a user has given their correct address when they pay, and hence know the correct tax to charge. However we believe tax authorities would generally recognise that such fraud is the fault of users rather than your own liability (this is standard practice), plus the address is also used for shipping which creates a reasonable barrier to fraud.
  • Before a buyer's address is known taxation is calculated as if the buyer was buying from the business's own address. This is so we can provide a "best estimate" of tax as early as possible.
  • We do not mention import duty in the software, which would often be due if shipping internationally. The buyer pays this to the shipping company before they will deliver the import. This is standard practice, and it is standard to not refer to it in eCommerce tax systems as it is outside the scope, but I thought it was worth mentioning.
  • We have designed the tax system to be legally compliant with at least EU and USA rules, although we cannot guarantee this – you must take your own responsibility for your legal compliance.
  • Sales tax rates may be changed, but they would be changed at the start of a new tax accounting period. Unless you are a USA seller using TaxCloud for all the taxes then you must be aware of this, ready to switch in new rates at midnight when the new ones apply.
  • Avoid taking and holding multiple currencies (e.g. on PayPal) unless you have a very good reason to – it will make your accounting particularly complicated. It is better to just force the buyer's credit card to charge in your own currency.
  • You should strongly consider setting the site timezone to that where you collect tax so that if tax rates change you can more easily tell what dates the transactions happened on.

Regional considerations

USA users

Basically if you are selling products commercially must register with your state for sales tax. Services usually are not liable for sales tax.

USA tax is extremely complex as it may be levied at the federal level, state level, county level, and city level. For most USA states the tax is charged based on where the buyer resides ("destination taxation"), not the seller ("origin taxation"). That is, unless the buyer is in a state where you don't have any operations centre (in which case no sales tax applies at all unless there's a federal tax which is rare †).
All the taxes need to be individually tracked and paid out.

As mentioned above we use the TaxCloud to handle most of the complexity.

To use the TaxCloud system:
  1. Your site must have working SSL functionality (outbound)
  2. Set up an account on TaxCloud
  3. Set up required details on the TaxCloud Profile/Websites/Contacts/Locations tabs; you will need your filing details such as your Federal Tax ID (EIN)
  4. Set up your payment information in the TaxCloud Payment Information tabs
  5. Consider adding the "Sales Tax Policy" text to your Composr rules page
  6. Fill in the TaxCloud API key configuration option on your Composr site
  7. Fill in the TaxCloud API ID configuration option on your Composr site
  8. Set the Business country configuration option on your Composr site to US
  9. Set the Business state configuration option on your Composr site to the state you operate your business from (make sure you enter a 2-character state code in upper-case, not the full written state name)
  10. You may ignore the "Tax countries" and "Tax states" Composr configuration options
  11. Set the Currency configuration option on your Composr site to USD
  12. Configure tax configuration options, and shopping catalogue items, to use the appropriate TIC code(s)
Note that TaxCloud will automatically debit the tax from you and do tax forms for you in many cases – and in any case will keep records of all the itemised sales taxes due.

Known limitations at this time which could be worked around with custom code…
  • We don't support exemption certificates for buyers not needing to pay tax (e.g. some farmers in some cases)

† Instead of sales tax charged at point of sale, most sites have something called 'use tax'. 'Use tax' should be paid by the buyer themselves when they file their taxes. Very few people do, make of that what you will.

EU users

Sales tax in the EU is known as "VAT". It is technically different from a normal sales tax, but we don't need to get into that in this tutorial. There is a configuration option to make sure that the term "VAT" is used instead of the term "Sales tax".

Basically if you are selling products or services commercially must register with your government's tax office for VAT.
In the UK and some other countries there is an income threshold after which you need to register. If you don't you can't get rebate on purchases you make, but you also benefit competitively by being able to charge buyers less money. If you are selling digital goods then there is no threshold, you must collect VAT and remit it (e.g. via the "MOSS" if you are based in UK).

Known limitations at this time which could be worked around with custom code…

The EU system for calculating digital product taxes charges the tax rate of the buyer's country, not yours, and is then paid to the government in the buyer's country.
It only applies to certain digital sales, not shipped products. To use digital product tax:
  1. You may ignore the "Tax countries" and "Tax states" configuration options unless you sell other products that have other tax codes
  2. Configure tax configuration options, and shopping catalogue items, to use the "EU digital goods tax" tax code

Other users

Known limitations at this time which could be worked around with custom code…
  • No special consideration has been given for tax rules in any other particular jurisdiction – instead we have tried to make it configurable

Tax invoices

Tax invoices are automatically created and delivered to buyers. They are also available from the Admin Zone.

Line items

Local laws may require tax invoices that show individual line items, each with their own tax rate. For example, shipping costs may be zero-rated, services may be given a service rate, and food may be given a food rate.

We support line items for:
  • shopping cart purchases: each individual item purchased is shown as a line item, as well as shipping costs.
  • for all eCommerce products that support a defined shipping cost we support showing this as a separate line item.

We do not support inputting line items individually in the Composr invoice system (separate from tax invoices). Composr invoices are designed for simple invoices with a common tax code covering the whole value of the invoice. You may workaround the limitation in 2 ways:
  1. by manually preparing your own tax invoices, using the Composr system for tracking and payment, but not for any kind of official records. The tax code produced would be custom-calculated as the effective percentage tax rate covering the overall invoice.
  2. create multiple invoices, so that you don't actually require separate line items

The same limitation applies to subscriptions, although this is not likely to be an issue as usually subscriptions wouldn't contain separate taxable items within them. The tax regulators would likely consider the subscription "atomic".

If you are setting up custom products it is possible these represent aggregate purchases and may suffer from this problem. However you likely could make a convincing case that it was all one "atomic" purchase also.

Tax derivation

The tax derivations will be needed for tax remittance if you are subject to EU digital goods tax, or to USA destination taxation.

We generally track these and they are available when you do a CSV download of transactions.

However, TaxCloud doesn't actually provide us broken-down data of the taxes. So if you are a USA user using TaxCloud you'll find this data on TaxCloud itself.

Shipping

Handling shipping costs

You should not enable automatic shipping cost calculation on your payment gateway as Composr handles it for you. If shipping cost calculation was enabled then buyers would be double-charged for shipping.

You have 3 possible approaches for calculating shipping costs:
  1. Use the inbuilt configuration options for calculating shipping cost based on weight and dimensions. This may work reasonably if shipping costs are not going to vary by distance.
  2. Fill in the Shippo configuration to calculate based on weight, dimensions, and presumably distance. Shippo will provide an exact shipping cost by actual communication with your choice of shipping company. This is likely your best option as Shippo is free (you pay when you print shipping labels), although it may not work for businesses in every country.
  3. Customise the code. The shipping cost calculation in '1' has been kept very simple because it's impossible to create configurability to cover every scenario people will want globally. There are too many different special cases to cover. We have therefore architected the calculations to go through a simple common function that a programmer can override to add in additional behaviour if needed, calculate_shipping_cost.

Known limitations at this time which could be worked around with custom code…

Shippo

Shippo is free because they make money helping you print shipping labels. We don't currently provide any special integration with that feature though.

  1. Sign up to Shippo
  2. Log into your Dashboard
  3. Go to the API section
  4. Copy the Live Token and Test Token into your eCommerce configuration (Admin Zone > Setup > Configuration > eCommerce options > Shipping).
  5. Go to the Carriers section
  6. Disable all but one carrier account (as Composr does not currently support shipping option choices); make sure the carrier account you leave supports international shipping (DHL Express does not, for example)

Shipping addresses

Some custom profile fields are preinstalled to allow members to set their shipping address in their regular profile settings (instead of having to define it each time when they pay on the payment gateway). However by default these fields are not enabled, so you would need to edit them to enable 'Owner viewable' and 'Owner settable' for each field.

There are configuration options to define whether the fields are enabled, in Admin Zone > Setup > Configuration > User/usergroup options > Special CPFs to show.

Additionally by default these fields are not enabled for direct editing by users, so you would need to edit them to enable 'Owner viewable' and 'Owner settable' for each field.
You can find and edit the fields from:
Admin Zone > Tools > Members > Custom Profile Fields > Edit Custom Profile Field

The configuration options also impact what shipping/billing address fields show, but subtly:
  • County input:
    • If the County field is disabled then County input will not be available
  • State input:
    • If the State field is disabled then State input will not be available, unless the Business country is US (as it is required for tax calculation)
    • If the Business country is US then State input will be a drop-down list, otherwise it will be a free-text input
    • If the Country field is enabled or the Business country is not US then an 'N/A' option will be included on the list (to signify a non-USA state)
    • If a buyer's state selection is not appropriate for the country selection then an error message will be shown
  • Postcode/Zip input:
    • If the Postcode/Zip field is disabled then Postcode/Zip input will not be enabled, unless the Business country is US (as required for tax calculation)
    • If a buyer's Postcode/Zip selection is not appropriate for the country selection then an error message will be shown
  • Country input:
    • If the Country field is disabled the Business country will be used automatically for the buyer's shipping/billing address

Auditing

Handling refunds

Image

Sales list management

Sales list management

(Click to enlarge)

There is a module in the Admin Zone for sales list management at:
Admin Zone > Audit > eCommerce sales list management
The module should be used to cancel purchases, such as an e-mail address purchased up a user that is no longer valid. Cancelling such a purchase allows a re-purchase at a later date (only one address of each e-mail address type is allowed per-user).

You may also want to cancel whatever the purchase automatically did. This is not done automatically for you (†). For example, if a user bought name highlighting you can edit their account to un-highlight their name.

Cancelling does not automatically provide a refund.

For monetary payments:
Refunds should be done on the payment gateway.

For point payments:
Refunds must manually be given through the points system.

† Usergroup subscriptions can be cancelled from the subscriptions page, or from some payment gateways. Usergroup memberships automatically are removed when a subscription is terminated.

Charts

Image

A profit/loss account for a fresh install

A profit/loss account for a fresh install

(Click to enlarge)

Composr includes some basic accountancy charting support. This is not intended as a replacement for a proper accountancy system, but does serve as a very useful overview of finances and a record of activity.

Composr can generate the following charts over a custom specified period:
  • Profit and loss account (Admin Zone > Audit > eCommerce > Profit/Loss account)
  • Cash flow diagram (Admin Zone > Audit > eCommerce > Cash flow diagram)

Not for formal accounting purposes

The developers do not accept any responsibility for the financial accounts of users of the Composr eCommerce system. Accountancy features are provided as an aid only and are not guaranteed to perform to match any legislative, tax, or accountancy conventions.

Logs

Transaction logs can be viewed from:
Admin Zone > Audit > eCommerce > Logs

Payment gateways: advanced

Manual transactions

Image

Inputting a manual transaction

Inputting a manual transaction

(Click to enlarge)

Normally a transaction would go through via PayPal/etc. i.e. Composr sends a user off to PayPal, and then PayPal calls back saying the transaction has happened.

However, we've designed it to be modular. In Composr another method of doing a transaction is the 'manual transaction'. The manual transaction form just allows you to simulate a transaction from the Admin Zone; the idea is that you've received a cheque (or SMS payment, or whatever) and are manually telling Composr about it so that Composr can dispatch the sale. To perform a manual transaction you need to:
  1. access the manual transaction screen (Admin Zone > Audit > eCommerce > Manual transaction).
  2. select the right product
  3. enter the correct ID number that the product will use to dispatch for this sale
  4. enter the sale amount that the product expects to be receiving (which you can leave blank for it to work this out itself).

Manual transactions may also be used to input transactions that are totally external to Composr, and thus otherwise immeasurable by the charting. For example, an organisations expenditure may be recorded by manually inputting a negative transaction for the special 'Other' product.

Local payments

Composr supports taking in payments 'locally' (i.e. not redirecting to a third-party site to take the payment). Not all the payment gateways within Composr allow local payments though, either due to the gateways not supporting it or just because it has not yet been implemented. At the time of writing the SecPay and Authorize.Net gateways support it.

Local payments should be considered with great caution because it requires a high level of PCI compliance, a very complex and expensive (increasingly so) process that carries legal liability.

You will need a more expensive webhost that provides PCI compliance.

We have summarised the PCI compliance rules below in a way streamlined toward Composr. This summary is not a full representation of PCI compliance and you should read through everything yourself.

Headline Rule Applies to webhost Applies to website
Hardware firewall Have a hardware firewall that sits in front of all inbound traffic. Every protocol allowed through the firewall must have a strict justification. The webhost must maintain full schematic documentation around the firewall, including all possible data flows. Everything must be reviewed every 6 months. Yes No
Software firewall Any computer used to connect to the webhosting must have a software firewall enabled (e.g. the ones that come with Windows and MacOS). Yes Yes
Antivirus Your webhosting servers, and any computer used to connect to the webhosting, must have anti-virus software enabled. This must be kept updated, do periodic scans and keep logs which are retained. Yes Yes
Penetration testing A PCI-approved scanning vendor must perform quarterly penetration testing on the network, repeating it until it passes. Yes No
Intrusion detection (1) Run fully-updated intrusion detection systems; any attacks or failures recorded and reported to management in a timely manner. Run a change detection system on core operating system files at least weekly. Yes No
Intrusion detection (2) Enable "Hacker/bot detected" notifications on an active administrator account in Composr. Run the rootkit_detector addon at least weekly. No Yes
Accurate logging Normal system logging must be fully enabled, not tampered with, and kept for at least a year. The last 3 months of logging must be immediately available. The system clock must be synched to an online source. Yes Yes
Active security auditing Logs must be reviewed daily and any attacks or failures recorded and reported to management in a timely manner. Yes Yes
Limit access Only people needing the access may be given it to the extent that they need that access. Yes Yes
Separate accounts Each user must have their own account. Yes Yes
No default access No default passwords or unnecessary privileged default accounts may be in place. Yes No
Disable inactive accounts Inactive accounts must be disabled after 90 days using the Composr "Password expiry days" option. No Yes
Stay patched Maintain an inventory of all relevant hardware and software items. Assess the security of each item. Keep all items patched for vulnerabilities, preferably via automatic nightly updates. Discard or replace anything that cannot be patched. Yes Yes
Secure shared hosting If using shared hosting then webhosting accounts must be fully isolated from each other, using a suEXEC-style system. This is basic and already recommended under our webhosting recommendations. Additionally consideration needs to be given to ensure log files are both maintained and isolated. Yes No
VPN Low level access to the webhosting (e.g. an SSH shell, phpMyAdmin, or a webhosting control panel) must require a VPN involving a secure key as well as the regular passwords. Each individual accessing user must have their own secure key. Yes No
Two-factor-authentication Within Composr the "Enquire on new IPs" option must be enabled on any administrative usergroups. All administrative users must understand why this is the case via a documented policy. No Yes
Database isolation The web server and MySQL server must be different machines [this actually comes from PA DSS]. Yes No
Physical security The physical facilities must be kept secure with access control, ID badges, and video cameras. Sensitive areas in the facility must only be accessible to those that need it. The webhost must immediately revoke access for terminated employees or visitors leaving. Visitors must be audited in a log book (saying visitor name, company, and authorising employee). This book must be kept for at least 3 months. Yes No
Secure backups All physical backup media must be kept securely, strongly encrypted, access-limited, and destroyed when no longer needed. Yes Yes
No wifi Look for, and maintain an inventory of, any wifi networks connected to the webhosting network, on a quarterly basis. Any unauthorised networks must be recorded and reported to management in a timely manner. Yes No
SSL Use an SSL certificate for at least access to the purchase, shopping, invoices, members, join and login modules. Preferably just use an HTTPS base URL. No Yes
Avoid storing card data Only enable the "Store credit card numbers" option if it is important to your business. No Yes
Screen developers Ensure any developers hired are highly competent at secure coding. No Yes
Information Security Policy Maintain an Information Security Policy. This must be in writing, cover all aspects of PCI compliance, kept updated, disseminated across staff, reviewed at least yearly, and compliance checked at least quarterly. It should include risk assessments, usage policies. There needs to be a process for initiating a timely forensic investigation in the case of a breach. Yes Yes
Screen staff Staff should be screened for criminal records, credit history, and employment history. Yes Yes


Concepts

PayPal
The most popular online payment gateway
Payment gateway
A third-party infrastructure for performing eCommerce transactions
Instant Payment Notification
A system, originally created by PayPal, for determining the progress of a financial transaction or ongoing subscription.
Product
An item in the eCommerce system that defines everything relating to the natural view of a product or service, including handling of any actions associated with a sale being completed or retracted; these products are not like supermarket products – they are very aggrandised and dynamic
PCI
The trade body for regulating eCommerce standards. When we refer to PCI compliance we are typically referring to PCI Data Security Standard (PCI DSS).
Shopping catalogue
A special catalogue for listing items that may be purchased through the shopping cart
Shopping catalogue item
An individual item in a shopping catalogue, another name for a catalogue entry which only applies to a shopping catalogue
Shopping cart
System for collecting and paying for one of more items from a shopping catalogue; typically these will be physical items that are shipped together
Purchasing module
The purchase module where one-off purchases are made
Subscription
Something purchased that has recurring payments for as long as the subscription is open
Invoice
An invoice created for a website member to pay
Unit price
The price of an item (gross, i.e. pre-tax), before quantity multiplication is applied
Price
The price of an item(s) (gross, i.e. pre-tax); this term is used roughly
Amount
The amount being paid in a transaction; this term is used roughly and may or may not include the sales tax
Grand total
The total cost of an order including tax and shipping costs
Fee
A fee levied on your website for processing a transaction
Origin taxation
USA taxation where taxes are levied based on where the seller (you) resides
Destination taxation
USA taxation where taxes are levied based on where the buyer resides
Sales tax
The system for charging tax on sales, used in the USA and other countries
Use tax
The system for paying tax on purchases, used in the USA; buyers are meant to report purchases from other states they paid no tax on and pay those taxes
VAT
Alternative to a sales tax system, used in the EU and some other countries around the world
Tax code
The Composr term for identifying a particular kind of taxation to apply to a product
Tax derivation
The Composr term for tracking what exact taxes are levied for a transaction
EU digital goods taxation
A tax system in Europe that applies to digital sales, taxes are paid to the buyer's home country using that country's own tax rate
Tax invoice
A formal (legally-compliant) invoice showing exactly what was paid for a transaction, broken down by line-item, with individual taxation rates shown for each line-item
TaxCloud
A third-party web service for handling the complexities of USA taxation

See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.