HTML Request Fields

Helcim.js will intercept your form data based on the respective HTML input elements field ID value. It will then send that information as a payload to the Helcim API to process either a Verify, Pre-Auth, or Purchase transaction, depending on the selection in your Helcim.js configuration.

Below is a list of all fields that can be set as part of a Helcim.js implementation to be included in your request.

❗️

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.

Required Input Fields

The following table outlines the HTML input fields that are required in order to process a payment through your Helcim.js integration.

This includes the field to pass your Helcim.js Configuration token, in addition to relevant fields to collect credit card information and complete address verification.

Field IDTypeDescription
tokenhiddenThe value of this hidden field should be your Helcim.js Configuration token.
cardNumbertextThe value of this field should be the credit card number to be used for processing. It must not include any spaces or special characters.
cardExpirytextThe value of this field should be the credit card expiry, in the MMYY format. It must not include any spaces or special characters separating the month and year values. Alternatively you may send cardExpiryMonth and cardExpiryYear separately, as outlined below.
cardExpiryMonthtextThe value of this field should be the credit card expiry month, in the MM format, such as 01 for January, or 11 for November. When sending cardExpiryMonth in this manner, you should also send the cardExpiryYear in it's relevant input field.
cardExpiryYeartextThe value of this field should be the credit card expiry year, in the YY or YYYY format. When sending cardExpiryYear in this manner, you should also send the cardExpiryMonth in it's relevant input field.
cardCVVtextThe value of this field should be the credit card security code (CVV/CVC), as a 3 or 4 digit value.
cardHolderNametextThe value of this field should be the credit card holders name, as it appears on their card.
cardHolderAddresstextThis value of this field should be the credit card holders address. This value is used to complete address verification for additional fraud protection, but does not impact the outcome of the transaction.
cardHolderPostalCodetextThis value of this field should be the credit card holders postal code or zip code. This value is used to complete address verification for additional fraud protection, but does not impact the outcome of the transaction.
<!--SETTINGS-->
<input type="hidden" id="token" value="58ae1d44d7ac6959332969">

<!--CARD-INFORMATION-->
<input type="text" id="cardNumber" value="5454545454545454">
<input type="text" id="cardExpiry" value="1025">
<input type="text" id="cardExpiryMonth" value="10">
<input type="text" id="cardExpiryYear" value="25">
<input type="text" id="cardCVV" value="100">

<!--AVS-INFORMATION-->
<input type="text" id="cardHolderName" value="Jane Smith">
<input type="text" id="cardHolderAddress" value="123 Street South">
<input type="text" id="cardHolderPostalCode" value="90210">

Optional Input Fields

The following tables outline the HTML input fields that are optional when processing a payment through your Helcim.js integration and should be included within the helcimForm element in your websites HTML.

They include optional settings fields, transaction amount and amountHash fields, billing and shipping fields, and order item fields.

Amount and Settings Fields

These fields can be used to set the customer's transaction, the amount hash, whether shipping, tax, or discounts are included, as well as link transactions to existing Customers or Invoices in the Helcim system.

Field IDTypeDescription
languagehiddenThe value of this field will set the language that Helcim.js displays error messages in. By default, this will return errors messages in "en", for English, but may also be "fr" for French, or "sp" for Spanish.
testhiddenThe value of this field can be set to "1" to process payments in test-mode. You should also turn on Test Mode for your Helcim.js Configuration settings in your Helcim account. Transactions will show in your Test Transaction list, which you can select from the dropdown in your Payments section in your Helcim account.
amounthiddenThe value of this field will set the transaction amount for the payment through Helcim.js. This field is not required if Helcim.js is being used to complete a Verify transaction, as that amount is $0.00 by default.
amountHashhiddenThe value of this field will be the amount hash for the transaction and is only required if Enforce Hashing is enabled for your Helcim.js Configuration. Review our documentation on Utilizing Amount Hashing to learn more.
amountShippinghiddenThe value of this field will be the shipping amount indicated on the invoice created by the Helcim.js Purchase or Pre-Authorize transaction.
amountTaxhiddenThe value of this field will be the tax amount indicated on the invoice created by the Helcim.js Purchase or Pre-Authorize transaction.
amountDiscounthiddenThe value of this field will be the discount amount indicated on the invoice created by the Helcim.js Purchase or Pre-Authorize transaction.
customerCodehiddenPassing the customerCode of an existing Customer object as the value for this field, will link the transaction and card details to this existing customer in the Helcim system.
orderNumberhiddenPassing the orderNumber of an existing Invoice as the value for this field, will link the transaction to this existing Invoice object in the Helcim system.
commentshiddenThe value of this field will be stored in the comments section of the Invoice created by the Helcim.js Purchase or Pre-Authorize transaction.
g-recaptcha-responsehiddenThe value of this field will be set to the reCaptcha response received by Google and is only required if Require Captcha is enabled in your Helcim.js Configuration. Review our documentation on Enabling reCaptcha for Helcim.js to learn more.
dontSubmithiddenThe value of this field can be set to "1" when using Helcim.js and you do not want to submit the form back to your website after Helcim.js processes the payment.
<!--OPTIONAL-SETTINGS-->
<input type="hidden" id="language" value="en">
<input type="hidden" id="test" value="1">

<!--OPTIONAL-AMOUNT-->
<input type="text" id="amount" value="100.00">
<input type="hidden" id="amountHash" value="sjkn29s8ngm382gbaj9172akaj29188ahjsj19182usnaksklk1212891279217whsahjash812712">
<input type="hidden" id="amountShipping" value="10.00">
<input type="hidden" id="amountTax" value="5.00">
<input type="hidden" id="amountDiscount" value="7.95">

<!--OPTIONAL-CUSTOMER-->
<input type="hidden" id="customerCode" value="CST1000">

<!--OPTIONAL-ORDER-->
<input type="hidden" id="orderNumber" value="INV2020">

<!--OPTIONAL-COMMENTS-->
<input type="hidden" id="comments" value="Hello World">

Billing and Shipping Fields

These fields can be used to set the customer's billing and shipping information, as well as the order's billing and shipping information.

Field IDTypeDescription
billing_contactNamehiddenThe the billing address contact name.
billing_businessNamehiddenThe billing address business name.
billing_street1hiddenThe billing street address.
billing_street2hiddenThe billing street address.
billing_cityhiddenThe billing city.
billing_provincehiddenThe billing province.
billing_countryhiddenThe billing country.
billing_postalCodehiddenThe billing postal code.
billing_phonehiddenThe billing phone number.
billing_faxhiddenThe billing fax number
billing_emailhiddenThe billing email.
shipping_contactNamehiddenThe shipping contact name.
shipping_businessNamehiddenThe shipping business name.
shipping_street1hiddenThe shipping street address.
shipping_street2hiddenThe shipping street address.
shipping_cityhiddenThe shipping city.
shipping_provincehiddenThe shipping province.
shipping_countryhiddenThe shipping country.
shipping_postalCodehiddenThe shipping postal code.
shipping_phonehiddenThe shipping phone number.
shipping_faxhiddenThe shipping fax number.
shipping_emailhiddenThe shipping email address.
<!--OPTIONAL-BILLING-ADDRESS-->
<input type="hidden" id="billing_contactName" value="Jane Smith">
<input type="hidden" id="billing_businessName" value="ABC Business">
<input type="hidden" id="billing_street1" value="303 Avenue North">
<input type="hidden" id="billing_street2" value="Unit 1403">
<input type="hidden" id="billing_city" value="Calgary">
<input type="hidden" id="billing_province" value="Alberta">
<input type="hidden" id="billing_country" value="Canada">
<input type="hidden" id="billing_postalCode" value="T2H 1K7">
<input type="hidden" id="billing_phone" value="403-555-1234">
<input type="hidden" id="billing_fax" value="403-555-2233">
<input type="hidden" id="billing_email" value="[email protected]">

<!--OPTIONAL-SHIPPING-ADDRESS-->
<input type="hidden" id="shipping_contactName" value="John Smith">
<input type="hidden" id="shipping_businessName" value="ABC Business USA">
<input type="hidden" id="shipping_street1" value="400 Street West">
<input type="hidden" id="shipping_street2" value="Unit 12">
<input type="hidden" id="shipping_city" value="Seattle">
<input type="hidden" id="shipping_province" value="WA">
<input type="hidden" id="shipping_country" value="USA">
<input type="hidden" id="shipping_postalCode" value="90221">
<input type="hidden" id="shipping_phone" value="814-555-1233">
<input type="hidden" id="shipping_fax" value="814-555-6633">
<input type="hidden" id="shipping_email" value="[email protected]">

Order Item Fields

Note that for all item field id values, replace "#" with a unique item number, starting at 1 and increasing by 1 for each unique item added.

Field IDTypeDescription
itemSKU#IntegerThe product SKU. Note that itemSKU# is a required for each lineItem sent through Helcim.js.
itemDescription#StringThe item description.
itemSerialNumber#StringThe item serial number.
itemQuantity#DecimalItem quantity, must be at least one for item to be added.
itemPrice#DecimalThe item price.
itemTotal#DecimalThe item price x the quantity.
<!--OPTIONAL-ORDER-ITEMS-->
<input type="hidden" id="itemSKU1" value="SKU123">
<input type="hidden" id="itemDescription1" value="The First Item">
<input type="hidden" id="itemSerialNumber1" value="SN109102991">
<input type="hidden" id="itemQuantity1" value="2.00">
<input type="hidden" id="itemPrice1" value="5.00">
<input type="hidden" id="itemTotal1" value="10.00">

<input type="hidden" id="itemSKU2" value="SKU456">
<input type="hidden" id="itemDescription2" value="The Second Item">
<input type="hidden" id="itemSerialNumber2" value="SN1091209310293">
<input type="hidden" id="itemQuantity2" value="1.00">
<input type="hidden" id="itemPrice2" value="17.00">
<input type="hidden" id="itemTotal2" value="17.00">