HelcimPay.js Implementation

This reference details the steps for rendering the HelcimPay.js modal using your valid checkoutToken.


Before beginning implementation:

Ensure that you have completed the HelcimPay.js Initialization process prior to proceeding with this section.

This reference explains the process for integrating HelcimPay.js on your webpage to render the HelcimPay.js payment modal and start processing payments.

Rendering HelcimPay.js

The HelcimPay.js modal is an iFrame that is overlaid on your webpage. To display it, first you must add a script tag to the head section of your HTML page with the given source URL, as shown.

<script type="text/javascript" src="https://secure.helcim.app/helcim-pay/services/start.js"></script>

The script allows access to the start.js file that holds the appendHelcimPayIframe function, which appends the iFrame on your webpage. The following table presents the parameters that the function takes as input

checkoutTokenStringRequiredThe token used for displaying the HelcimPay.js modal. Obtained through the HelcimPay.js Initialization process
allowExitBooleanOptionalDefaulted to true. A boolean that controls the display of the exit icon in the HelcimPay.js modal.

Example implementation:

<a href="javascript: appendHelcimPayIframe(checkoutToken, false)">
  Pay Now

This JavaScript function can be invoked in different ways on the webpage, such as by a link or button. When invoked, the function will render the iframe that displays the modal. Users can then fill out the form present on the modal with their information and can start the payment by clicking on the Process Payment button.


Listening to Response Events

By clicking the Process Payment button, the payment process is initiated. After the process finishes, the transaction response can be retrieved by listening to the response emitted by the iFrame as shown.

window.addEventListener('message', (event) => {
  const helcimPayJsIdentifierKey = 'helcim-pay-js-' + checkoutToken;
  if(event.data.eventName === helcimPayJsIdentifierKey){
    if(event.data.eventStatus === 'ABORTED'){
       console.error('Transaction failed!', event.data.eventMessage);
    if(event.data.eventStatus === 'SUCCESS'){
      console.log('Transaction success!', event.data.eventMessage);


Note: The checkoutToken is provided during the HelcimPay.js Initialization process.

The following table summarizes the event variables emitted by the HelcimPay.js iFrame.

eventNameAn identifier that indicates that the postMessage is from the HelcimPay.js iFrame.

eventStatusIndicates the outcome of the transaction process.

eventMessageThe response from the transaction process, which can only either be:
- A transaction response object that indicates that the process is successful
- An error message saying "HelcimPay.js transaction failed - additional-error-message-here"

Transaction Response

When a HelcimPay.js credit card transaction is processed, the eventMessage contains a JSON.stringify version of the response. Below is an example of a parsed response object.

status: 200
data: {
  data: {
    amount: "100.00",
    approvalCode: "T5E5ST",
    avsResponse: "X",
    cardBatchId: "2578965",
    cardHolderName: "Jane Doe",
    cardNumber: "5454545454",
    cardToken: "684a4a03400fadd1e7bdc9",
    currency: "CAD",
    customerCode: "CST1200",
    dateCreated: "2022-01-05 12:30:45",
    invoiceNumber: "INV000010",
    status: "APPROVED",
    transactionId: "17701631",
    type: "purchase"
  hash: "dbcb570cca52c38d597941adbed03f01be78c43cba89048722925b2f168226a9"

When a HelcimPay.js bank transaction is successful, the eventMessage contains a JSON.stringify version of the response. Below is an example of a parsed response object.

status: 200
data: {
  data: {
    amount: "100.00",
    approvalCode: "",
    bankAccountNumber: "100200300",
    bankToken: "fcc48b4cb9a8ecd6531b49",
    batchId: "0",
    currency: "CAD",
    customerCode: "CST1200",
    dateCreated: "2023-04-20 13:56:31",
    invoiceNumber: "INV000020",
    statusAuth: "PENDING",
    statusClearing: "OPENED",
    transactionId: "1020",
    type: "WITHDRAWAL"
  hash: "dbcb570789b3cba8682c43cba899794103f0122adbed6a26e048722925b2f168"

The data in the response data can be validated to ensure it was not manipulated, which is covered in HelcimPay.js Validation documentation.