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 ID | Type | Description |
|---|---|---|
| token | hidden | The value of this hidden field should be your Helcim.js Configuration token. |
| cardNumber | text | The value of this field should be the credit card number to be used for processing. It must not include any spaces or special characters. |
| cardExpiry | text | The 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. |
| cardExpiryMonth | text | The 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. |
| cardExpiryYear | text | The 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. |
| cardCVV | text | The value of this field should be the credit card security code (CVV/CVC), as a 3 or 4 digit value. |
| cardHolderName | text | The value of this field should be the credit card holders name, as it appears on their card. |
| cardHolderAddress | text | This 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. |
| cardHolderPostalCode | text | This 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 ID | Type | Description |
|---|---|---|
| language | hidden | The 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. |
| test | hidden | The 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. |
| amount | hidden | The 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. |
| amountHash | hidden | The 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. |
| amountShipping | hidden | The value of this field will be the shipping amount indicated on the invoice created by the Helcim.js Purchase or Pre-Authorize transaction. |
| amountTax | hidden | The value of this field will be the tax amount indicated on the invoice created by the Helcim.js Purchase or Pre-Authorize transaction. |
| amountDiscount | hidden | The value of this field will be the discount amount indicated on the invoice created by the Helcim.js Purchase or Pre-Authorize transaction. |
| customerCode | hidden | Passing the customerCode of an existing customer as the value for this field, will link the transaction and card details to this existing customer in the Helcim system. If the card details used for processing already exist, the existing card object will be used, if they do not then the Helcim system will create a new card object and cardToken for the customer linked. |
| orderNumber | hidden | Passing 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. |
| comments | hidden | The 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-response | hidden | The 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. |
| dontSubmit | hidden | The 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 ID | Type | Description |
|---|---|---|
| billing_contactName | hidden | The the billing address contact name. |
| billing_businessName | hidden | The billing address business name. |
| billing_street1 | hidden | The billing street address. |
| billing_street2 | hidden | The billing street address. |
| billing_city | hidden | The billing city. |
| billing_province | hidden | The billing province. |
| billing_country | hidden | The billing country. |
| billing_postalCode | hidden | The billing postal code. |
| billing_phone | hidden | The billing phone number. |
| billing_fax | hidden | The billing fax number |
| billing_email | hidden | The billing email. |
| shipping_contactName | hidden | The shipping contact name. |
| shipping_businessName | hidden | The shipping business name. |
| shipping_street1 | hidden | The shipping street address. |
| shipping_street2 | hidden | The shipping street address. |
| shipping_city | hidden | The shipping city. |
| shipping_province | hidden | The shipping province. |
| shipping_country | hidden | The shipping country. |
| shipping_postalCode | hidden | The shipping postal code. |
| shipping_phone | hidden | The shipping phone number. |
| shipping_fax | hidden | The shipping fax number. |
| shipping_email | hidden | The 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 ID | Type | Description |
|---|---|---|
| itemSKU# | Integer | The product SKU. Note that itemSKU# is a required for each lineItem sent through Helcim.js. |
| itemDescription# | String | The item description. |
| itemSerialNumber# | String | The item serial number. |
| itemQuantity# | Decimal | Item quantity, must be at least one for item to be added. |
| itemPrice# | Decimal | The item price. |
| itemTotal# | Decimal | The 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">
Updated 3 months ago