Helcim Gateway

Code Samples

Compatible Carts

Sample Policies

Internet Requirements

Affiliate Program

Ingenico i5100

Sales, Refunds & Voids

Batch & Totals

Advanced Options

Terminal Updates

Resources

International Issuer Fee

Credit Card Logos

Card on Invoices

XML API Documentation

Helcim Virtual Store Support

For development support or to acquire a developer test account for the Helcim Virtual Store, contact us today.

Downloadable Format

Helcim_VirtualStore-XML-API-Documentation_v2.000.pdf

Introduction
Accessing the XML
XML Options
Custom Images
Products (XML Example)
Parents (XML Example)
Categories (XML Example)
Brands (XML Example)
Options (XML Example)
Coupons (XML Example)
Cart Colors (XML Example)
Store -Details (XML Example)
Policies (XML Example)
Shipping (XML Example)

Copyright © 2006 - 2009 Helcim Inc. All rights reserved.
The information contained in this document is subject to change without notice.
This document contains information protected by copyright.
NO PART OF THIS DOCUMENT MAY BE PHOTOCOPIED OR REPRODUCED IN ANY FORM WITHOUT PRIOR WRITTEN CONSENT FROM HELCIM INC.

Introduction

The Helcim Virtual Store Live Access feature allows you to easily display your product catalogue on your own website without having to maintain two databases. Changes made in your Virtual Store will automatically be updated on your own website. The Live Access feature allows you to get listings of all the available Virtual Store information including products, categories, parent categories, product options and store details. This can be done in a standard HTTP environment or in secure HTTPS.

Purpose of This Document

The purpose of this document is to outline the basic functionality of the Live Access feature. In particular it will give information on the XML structure and how to access the XML files.

Useful Links

If you would like to obtain more information on the XML specification you can visit:
http://www.w3.org/XML/

For information on parsing XML in PHP 5 visit:
http://ca.php.net/manual/en/book.simplexml.php

For PHP 4:
http://ca.php.net/manual/en/ref.xml.php

For ASP.NET:
http://msdn2.microsoft.com/en-us/library/system.xml.aspx

Requirements

In order to use the Live Access feature a general understanding of XML, as well as a server-side scripting language (such as: PHP, ASP or JSP) is required. Since the XML is located on our servers Javascript will not be sufficient as it will not allow you to load a file from a different domain.

However, if live updates are not a requirement, it is possible to copy the XML and save it locally; in which case you would be able to load the file using Javascript.

How it Works

The Live Access feature allows you to get an XML listing from our servers through a script on your own site. Our server will reply back with the XML file that you requested, which you can in turn use to display information on your site.

For example, if you wanted to get a listing of all of the products in your product catalogue:

In your scripting language of choice connect to:
http://xml.virtualstore.helcim.com/?type=product&merchant=your_merchant_id&token=your_xml_token
The response back will be an XML file with your requested information.
Parse the XML and display the information on your website.

Accessing the XML

There are two URLs to access the XML one for production use and one for development use. The production URL supports both HTTP and HTTPS. Currently the development URL can only be accessed in standard HTTP.

Production: xml.virtualstore.helcim.com
Development: demo.xml.virtualstore.helcim.com

XML Options

The XML also has extra options in the form of GET variables, some of which are mandatory. Options can be added by simply adding them to the URL. For example, to add the 'type' option to the XML query:

http://xml.virtualstore.helcim.com/?type=product

The first option in the URL is always preceded by a '?', each option after that is preceded by a '&':

http://xml.virtualstore.helcim.com/?type=product&merchant=your_merchant_id

There are three options that are mandatory for every XML request you send. They are:

type
The type of result you are looking for (product, category, etc..).

merchant
The merchant id, it's the same number you use to login to your account.

token
The XML token that needs to be generated in your Virtual Store before you can access the XML files. This token ensures that other sites can't pull your product catalogue without your knowledge and can be changed at anytime. Keep in mind that after your site is set up, if you change your XML token you will need to change your scripts so that they use the new token.

To generate your XML token:

Login to your Helcim Virtual Store.
Click on 'Store Options' on the upper menu.
Click on 'XML Remote Access' under 'Advanced Settings'
By default XML will be disabled. Select 'Yes' and click 'Save XML Settings Changes'.
An XML token will be generated for you. This is what you will put for the token option in any XML request you send.

There are also three common options that can be used for almost every type of XML:

orderBy
How you want your results ordered.

orderDir
What direction you want your results ordered ASC (ascending) or DESC (descending).

limit
Allows you to limit the number of results.

Custom Images

Custom images allow you to set custom image sizes for the product and event pictures you upload to your account. When adding a custom size you will be asked to input a prefix for your pictures. You can then add this prefix to the pictures pulled from the XML file in the form of: <picture directory> + <prefix> + <picture>.

To add a custom image size:

Login to your Helcim Virtual Store.
Click on 'Store Options' on the upper menu.
Click on 'Custom Image Sizes' under 'Advanced Settings'.
Enter a prefix for this image size, the size, and whether or not you want to force the image to be resized or if it should keep its ratio.
Click 'Add Preset'

Products

Type:	product
Optional Fields:	category, brand, product, parent, option, accessory, featured, onSale, getAccessories, tag, orderBy, orderDir, limit

Optional Fields

orderBy	Products support ordering by: id, name, sku, price, stock, featured, weight, shippingUnits, addedToCart and purchased.
category	Allows you to pull products from a specific category by entering the category id.
brand	Allows you to pull products with a specific brand by entering the brand id.
product	Allows you to pull only a specific product by id.
parent	Allows you to pull products from a specific parent category by entering the parent id.
option	Allows you to pull products that have a specific option. For example, if you sold clothing and had an option group called "Size" you could get all clothing of size small, by entering the option id here.
accessory	Allows you to pull products that have this product as an accessory.
featured	Allows you to pull only products marked as featured.
onSale	Allows you to pull only products that are on sale.
getAccessories	Allows you to pull only products that have been marked as accessories to other products. When used with the "product" option getAccessories will pull a list of accessories for that product.
tag	Allows you to pull products based on the entered tags. This option will split up all the words sent and search for products with tags that match any of the words.

Product XML Example

<?xml version="1.0"?>
<products>
	<product>
		<id>11</id>
		<category>
			<id>10</id>
			<name>Test Category 1</name>
		</category>
		<brand>
			<id>20</id>
			<name>Test Brand 1</name>
		</brand>
		<sku>SKU123</sku>
		<name>Product 1</name>
		<description>Test product number one.</description>
		<price>10.00</price>
		<originalPrice>15.00</originalPrice>
		<tags>tag1, tag2, tag3</tags>
		<weight>12.00</weight>
		<width>5.00</width>
		<height>10.00</height>
		<length>3.00</length>
		<shippingUnits>5</shippingUnits>
		<inStock>1</inStock>
		<featured>1</featured>
		<pictures>
			<path>http://virtualstore.helcim.com/pictures/products/</path>
			<main>mainpicture.jpg</main>
			<picture>picture.jpg</picture>
		</pictures>
		<options>
			<group>
				<id>1</id>
				<name>Group 1</name>
				<option>
					<id>10</id>
					<name>Option 1</name>
				</option>
				<option>
					<id>20</id>
					<name>Option 2</name>
				</option>
			</group>
		</options>
		<specifications>
			<specification>
				<name>Specification 1</name>
				<details>Specification information.</details>
			</specification>
			<specification>
				<name>Sepcification 2</name>
				<details>Specification information.</details>
			</specification>
		</specifications>
	</product>
</products>

Parents

Type:	parent
Optional Fields:	productBrand, productOption, productTag, parent, showZeroProducts, orderBy, orderDir, limit

Optional Fields

orderBy	Parents support ordering by: id, name.
productBrand	Changes the numberOfProducts returned based on a particular brand.
productOption	Changes the numberOfProducts returned based on a particular option.
productTag	Changes the numberOfProducts returned based on a particular tag.
parent	Allows you to pull only a specific parent by id.
showZeroProducts	Either 1 or 0 (1 by default), allows you to hide parents that do not contain any products.

Parents XML Example

<?xml version="1.0"?>
<parents>
	<parent>
		<id>38</id>
		<name>Parent 1</name>
		<description>Parent description 1.</description>
		<numberOfProducts>10</numberOfProducts>
	</parent>
</parents>

Brands

Type:	brand
Optional Fields:	productCategory, productOption, productTag, brand, showZeroProducts, orderBy, orderDir, limit

Optional Fields

orderBy	Brands support ordering by: id, name.
productCategory	Changes the numberOfProducts returned based on a particular category.
productOption	Changes the numberOfProducts returned based on a particular option.
productTag	Changes the numberOfProducts returned based on a particular tag.
brand	Allows you to pull only a specific brand by id.
showZeroProducts	Either 1 or 0 (1 by default), allows you to hide brands that do not contain any products.

Brands XML Example

<?xml version="1.0"?>
<brands>
	<brand>
		<id>25</id>
		<name>Brand 1</name>
		<description>Brand description.</description>
		<logoPath>http://virtualstore.helcim.com/pictures/brands/</logoPath>
		<logo>logo.jpg</logo>
		<numberOfProducts>3</numberOfProducts>
	</brand>
</brands>

Options

Type:	option
Optional Fields:	productBrand, productCategory, productTag, optionGroupId, showZeroProducts, orderBy, orderDir, limit

Optional Fields

orderBy	Options support ordering by: id, name.
productBrand	Changes the numberOfProducts returned based on a particular brand.
productCategory	Changes the numberOfProducts returned based on a particular category.
productTag	Changes the numberOfProducts returned based on a particular tag.
optionGroupId	Allows you to pull only the options from a specific option group.
showZeroProducts	Either 1 or 0 (1 by default), allows you to hide options that have not been added to any products.

Options XML Example

<?xml version="1.0"?>
<optionGroups>
	<optionGroup>
		<id>6</id>
		<name>Color</name>
		<numberOfProducts>9</numberOfProducts>
		<options>
			<option>
				<id>34</id>
				<name>Black</name>
				<numberOfProducts>7</numberOfProducts>
			</option>
			<option>
				<id>35</id>
				<name>Green</name>
				<numberOfProducts>3</numberOfProducts>
			</option>
			<option>
				<id>33</id>
				<name>White</name>
				<numberOfProducts>6</numberOfProducts>
			</option>
		</options>
	</optionGroup>
</optionGroups>

Coupons

Type:	coupon
Optional Fields:	code, generateNew, showOneTimeUse, showExpired, orderBy, orderDir, limit

Optional Fields

orderBy	Coupons support ordering by: id, code, name, discount, minimumPurchase, expiry.
code	Allows you to pull a specific coupon based on the coupon code.
generateNew	Will return a new coupon generated based off of the auto coupon settings.
showOneTimeUse	Either 1 or 0 (0 by default), shows or hides one time use coupons.
showExpired	Either 1 or 0 (0 by default), shows or hides coupons that have expired.

Coupons XML Example

<?xml version="1.0"?>
<coupons>
	<coupon>
		<code>PROMO10</code>
		<name>10% off everything!name>
		<discount>10.00</discount>
		<discountType>%</discountType>
		<discountShipping>0</discountShipping>
		<minimumPurchase>10.00</minimumPurchase>
		<expiresOn>2019-01-02</expiresOn>
		<oneTimeUse>0</oneTimeUse>
	</coupon>
</coupons>

Cart Colors

Type:	cartColors
Optional Fields:	none

Cart Colors XML Example

<?xml version="1.0"?>
<colors>
	<background>
		<color>FFC2C9</color>
		<image>https://virtualstore.helcim.com/pictures/
		cartPresets/Helcim_VTpreset11_pageback.jpg</image>
		<repeat>repeat-x</repeat>
		<align>top center</align>
	</background>
	<tableBackground>
		<color>FFE0E3</color>
		<image>https://virtualstore.helcim.com/pictures
		cartPresets/Helcim_VTpreset11_tableback.jpg</image>
		<repeat>repeat-x</repeat>
		<align>top center</align>
	</tableBackground>
	<cellOne>
		<color>FFEDEF</color>
	</cellOne>
	<cellTwo>
		<color>FFEBED</color>
	</cellTwo>
	<mainText>
		<color>932B52</color>
	</mainText>
	<subText>
		<color>AA6680</color>
	</subText>
	<tableBorder>
		<color>FFFFFF</color>
	</tableBorder>
	<link>
		<color>3196C0</color>
	</link>
	<activeLink>
		<color>1FBDFF</color>
	</activeLink>
</colors>

Store Details

Type:	storeDetails
Optional Fields:	none

Store Details XML Example

<?xml version="1.0"?>
<storeDetails>
	<contactInformation>
		<name>Helcim Inc</name>
		<address>#1A - 2016 25th Ave NE</address>
		<city>Calgary</city>
		<province>Alberta</province>
		<postalCode>T2E 6Z4</postalCode>
		<phoneNumber>(403) 291-1173</phoneNumber>
		<emailAddress>support@helcim.com</emailAddress>
	</contactInformation>
	<description>The quick descriptions is here.</description>
	<about>The detailed store description allows you to inform your customers.</about>
	<logoPath>http://virtualstore.helcim.com/pictures/logo/</logoPath>
	<logo>logo.jpg</logo>
	<acceptedCards>
		<card>Visa</card>
		<card>MasterCard</card>
		<card>American Express</card>	
	</acceptedCards>
</storeDetails>

Policies

Type:	policies
Optional Fields:	none

Policies XML Example

<?xml version="1.0"?>
<policies>
	<delivery>Delivery and return policy.</delivery>
	<privacy>Privacy policy.</privacy>
</policies>

Shipping

Type:	shipping
Optional Fields:	hideAllowances

Optional Fields

hideAllowances

Either 0 or 1 (0 by default), this option allows you to NOT pull the allowed countries/provinces/states.

Shipping XML Example

<?xml version="1.0"?>
<shipping>
	<canada>
		<methods>
			<method>
				<name>Standard Ground</name>
				<baseRate>12.00</baseRate>
				<perUnitRate>0.50</perUnitRate>
			</method>
			<method>
				<name>Expedited Air</name>
				<baseRate>15.00</baseRate>
				<perUnitRate>1.67</perUnitRate>
			</method>
		</methods>
		<allowedProvinces>Alberta, British Columbia, Manitoba</allowedProvinces>
	</canada>
	<unitedstates>
		<methods>
			<method>
				<name>Standard International Ground</name>
				<baseRate>20.00</baseRate>
				<perUnitRate>0.09</perUnitRate>
			</method>
			<method>
				<name>Priority International Air</name>
				<baseRate>30.00</baseRate>
				<perUnitRate>0.15</perUnitRate>
			</method>
		</methods>
		<allowedStates>Alabama, Alaska, Arizona, Arkansas</allowedStates>
	</unitedstates>
	<international>
		<methods>
			<method>
				<name>Overseas Ground (4-6 weeks)</name>
				<baseRate>50.00</baseRate>
				<perUnitRate>0.50</perUnitRate>
			</method>
			<method>
				<name>Overseas Air (1-2 weeks)</name>
				<baseRate>75.00</baseRate>
				<perUnitRate>0.50</perUnitRate>
			</method>
		</methods>
		<allowedCountries>Afghanistan, Albania, Algeria</allowedCountries>
	</international>
</shipping>

call us toll-free

1-877-6HELCIM

Toll Free	1 (877) 643-5246
Fax	1 (866) 469-3077

Our Platforms

Apply Now

Helcim

Merchant Services

Recent Helcim Blog Articles

Why you should consider giving free shipping... Monday, June 14, 2010
Promoting your store's website Monday, June 14, 2010
Is your credit card processor PCI-Level 1 certified? Wednesday, March 3, 2010
Canadian-Merchant-Accounts.ca Launched! Wednesday, February 17, 2010

The Helcim name and logo are trademarks of Helcim Inc. The Interac name and logo are trademarks of Interac Inc. The Visa and MasterCard logos are trademarks of Visa International and MasterCard International Incorporated. Other tradenames may be trademarks of their respective owners. Helcim is a registered MSP/ISO of the Canadian branch of U.S. Bank National Association and GE Money. New applicants are subject to conditions and approval of the application by Helcim and its partnering banks.

orderBy	Categories support ordering by: id, name.
productBrand	Changes the numberOfProducts returned based on a particular brand.
productOption	Changes the numberOfProducts returned based on a particular option.
productTag	Changes the numberOfProducts returned based on a particular tag.
parent	Allows you to pull only a categories from a specific parent by id.
showZeroProducts	Either 1 or 0 (1 by default), allows you to hide categories that do not contain any products.

XML API Documentation

Helcim Virtual Store Support

Downloadable Format

Table of Contents

Purpose of This Document

Useful Links

Requirements

How it Works

Optional Fields

Optional Fields

Optional Fields

Optional Fields

Optional Fields

Optional Fields

Optional Fields

Recent Helcim Blog Articles