Integrating with Helcim.js

Once you have completed your configuration steps for Helcim.js in your Helcim account, you’re ready to begin integrating Helcim.js into your website or application.

This process involves utilizing a number of HTML input elements in your payment flow, along with the Helcim.js script tags to call the JavaScript after the customer enters their card details and processes their transaction.

The following documentation outlines both the minimum required HTML input fields in order to process through Helcim.js, in addition to the more detailed optional HTML input fields.

❗️
Credit card information input fields
HTML input fields for sensitive credit card information should not have an HTML field name, only an HTML field id. This will allow the JavaScript to retrieve the values using getElementById, but prevent the fields from being submitted back to your server.
After processing the transaction Helcim.js will attempt to mask sensitive data before submitting the HTML form back to your website.

Helcim.js HTML required elements

The following table outlines the minimum HTML elements that are required to facilitate your integration with Helcim.js.

HTML element type	Element id	Format	Description
script		text/javascript	The Helcim.js JavaScript, with src="<https://secure.myhelcim.com/js/version2.js"
form	helcimForm	method=POST	The HTML `form` element contains the required and optional Helcim.js input fields outlined below. This element should have both a name and id value set to `helcimForm`. Once the transaction is complete, Helcim.js will submit the form back to the merchant server (website) to capture the transaction results.
div	helcimResults		The `div` content will be overwritten by Helcim.js, where it will display errors or transaction results before the form is finally submitted. This element should be inside the `helcimForm` element.
input type="hidden"	token
input type="text"	cardNumber		The field with the `id` of cardNumber where the customer will enter their credit card number.
input type="text"	cardExpiryMonth		The field with the `id` of cardExpiryMonth where the customer will enter their credit card expiry month in MM format.
input type="text"	cardExpiryYear		The field with the `id` of cardExpiryYear where the customer will enter their credit card expiry year in YY format.
input type="text"	cardCVV		The field with the `id` of cardCVV where the customer will enter their credit card CVV.
input type="button"	buttonProcess	onclick="javascript:helcimProcess();"	The input button to process the payment through Helcim.js. The value of this button can be set to anything, such as "Process Payment" or "Save Card".

The examples below show the required and optional input fields needed to process through Helcim.js, in addition to a more detailed example that includes a number of optional values that can be passed to record additional data.

👍
For a more detailed overview of the available Helcim.js input fields, you can review our documentation here.

Example HTML for Helcim.js required elements

The following code outlines the minimum required fields in order to process a credit card payment through Helcim.js. It includes the HTML elements outlined in the table above, in addition to the required input fields for processing.

This code can be copied directly into your website or applications HTML, however you will need to change the token value to your own Helcim.js Configuration token.

<!--SCRIPT-->
// Included in the head element of your website
<script type="text/javascript" src="https://secure.myhelcim.com/js/version2.js"></script>


<!--FORM-->
// Included in the body element of your website
<form name="helcimForm" id="helcimForm" action="your-checkout-page.php" method="POST">

	<!--RESULTS-->
	<div id="helcimResults"></div>

	<!--SETTINGS-->
	<input type="hidden" id="token" value="58ae1d44d7ac6959332969">
  
	<!--CARD-INFORMATION-->
	Credit Card Number: <input type="text" id="cardNumber" value=""><br/>
	Expiry Month: <input type="text" id="cardExpiryMonth" value=""> 
 	Expiry Year: <input type="text" id="cardExpiryYear" value=""><br/>
	CVV: <input type="text" id="cardCVV" value=""><br/>

	<!--AVS- INFORMATION-->
	Card Holder Name: <input type="text" id="cardHolderName" value=""><br/>
	Card Holder Address: <input type="text" id="cardHolderAddress" value=""><br/>
	Card Holder Postal Code: <input type="text" id="cardHolderPostalCode" value=""><br/>

	<!--OPTIONAL-AMOUNT-->
	Amount: <input type="text" id="amount" value="100.00"><br/>

	<!--BUTTON-->
	<input type="button" id="buttonProcess" value="Process" onclick="javascript:helcimProcess();">

</form>

📘
Using Helcim.js to complete a Verify transaction
When processing a Verify through Helcim.js, any value in the amount input field will be ignored, due to a Verify transaction always being a $0.00 amount by default.

Example HTML for Helcim.js optional elements

This example shows a complete list of possible input fields that you can include in your Helcim.js implementation. Again, the token value should be changed to your own Helcim.js Configuration token.

<!--SCRIPT-->
// Included in the head element of your website
<script type="text/javascript" src="https://secure.myhelcim.com/js/version2.js"></script>

<!--FORM-->
// Included in the body element of your website
<form name="helcimForm" id="helcimForm" action="your-checkout-page.php" method="POST">

	<!--RESULTS-->
	<div id="helcimResults"></div>

	<!--SETTINGS-->
	<input type="hidden" id="token" value="58ae1d44d7ac6959332969">
	<input type="hidden" id="language" value="en">

	<!--CARD-INFORMATION-->
	Card Token: <input type="text" id="cardToken" value="1"><br/>
	Credit Card Number: <input type="text" id="cardNumber" value=""><br/>
	Expiry Month: <input type="text" id="cardExpiryMonth" value="">
 	Expiry Year: <input type="text" id="cardExpiryYear" value=""><br/>
	CVV: <input type="text" id="cardCVV" value=""><br/>

	<!--AVS-INFORMATION-->
	Card Holder Name: <input type="text" id="cardHolderName" value=""><br/>
	Card Holder Address: <input type="text" id="cardHolderAddress" value=""><br/>
	Card Holder Postal Code: <input type="text" id="cardHolderPostalCode" value=""><br/>

	<!--OPTIONAL-AMOUNT-->
	Amount: <input type="text" id="amount" value="100.00"><br/>
	<input type="hidden" id="amountShipping" value="2.00">
	<input type="hidden" id="amountTax" value="3.00">

	<!--OPTIONAL-BILLING-ADDRESS-->
	Billing - Contact Name: <input type="text" id="billing_contactName" value=""><br/>
	Billing - Business Name: <input type="text" id="billing_businessName" value=""><br/>
	Billing - Address Street 1: <input type="text" id="billing_street1" value=""><br/>
	Billing - Address Street 2: <input type="text" id="billing_street2" value=""><br/>
	Billing - City: <input type="text" id="billing_city" value=""><br/>
	Billing - Province: <input type="text" id="billing_province" value=""><br/>
	Billing - Postal Code: <input type="text" id="billing_postalCode" value=""><br/>
	Billing - Country: <input type="text" id="billing_country" value=""><br/>
	Billing - Phone Number: <input type="text" id="billing_phone" value=""><br/>
	Billing - Email Address: <input type="text" id="billing_email" value=""><br/>
	Billing - Fax: <input type="text" id="billing_fax" value=""><br/>

	<!--OPTIONAL-SHIPPING-ADDRESS-->
	Shipping - Contact Name: <input type="text" id="shipping_contactName" value=""><br/>
	Shipping - Business Name: <input type="text" id="shipping_businessName" value=""><br/>
	Shipping - Address Street 1: <input type="text" id="shipping_street1" value=""><br/>
	Shipping - Address Street 2: <input type="text" id="shipping_street2" value=""><br/>
	Shipping - City: <input type="text" id="shipping_city" value=""><br/>
	Shipping - Province: <input type="text" id="shipping_province" value=""><br/>
	Shipping - Postal Code: <input type="text" id="shipping_postalCode" value=""><br/>
	Shipping - Country: <input type="text" id="shipping_country" value=""><br/>
	Shipping - Phone Number: <input type="text" id="shipping_phone" value=""><br/>
	Shipping - Email Address: <input type="text" id="shipping_email" value=""><br/>
	Shipping - Fax: <input type="text" id="shipping_fax" value=""><br/>

	<!--OPTIONAL-ORDER-->
	Order Number: <input type="text" id="orderNumber" value="4"><br/>

	<!--OPTIONAL-CUSTOMER-->
	Customer Code: <input type="text" id="customerCode" value="3"><br/>

	<!--OPTIONAL-COMMENTS-->
	Comments: <input type="text" id="comments" value=""><br/>

	<!--OPTIONAL-ITEM-->
	ITEM 1 - SKU: <input type="text" id="itemSKU1" value="SKU100"><br/>
	ITEM 1 - Description: <input type="text" id="itemDescription1" value="Item 1 Description"><br/>
	ITEM 1 - Serial Number: <input type="text" id="itemSerialNumber1" value="SN10100100101"><br/>
	ITEM 1 - Quantity: <input type="text" id="itemQuantity1" value="2"><br/>
	ITEM 1 - Price: <input type="text" id="itemPrice1" value="10.00"><br/>
	ITEM 1 - Total: <input type="text" id="itemTotal1" value="20.00"><br/>

	ITEM 2 - SKU: <input type="text" id="itemSKU2" value="SKU200"><br/>
	ITEM 2 - Description: <input type="text" id="itemDescription2" value="Item 2 Description"><br/>
	ITEM 2 - Serial Number: <input type="text" id="itemSerialNumber2" value="SN20200200202"><br/>
	ITEM 2 - Quantity: <input type="text" id="itemQuantity2" value="2"><br/>
	ITEM 2 - Price: <input type="text" id="itemPrice2" value="15.00"><br/>
	ITEM 2 - Total: <input type="text" id="itemTotal2" value="30.00"><br/>

	<!--BUTTON-->
	<input type="button" id="buttonProcess" value="Process" onclick="javascript:helcimProcess();">

</form>