HelcimPay.js Implementation

Ensure you've 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 start processing payments.

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 function requires one input, checkoutToken, which is obtained through the HelcimPay.js Initialization process.

Example implementation:

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

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 Events

By clicking the Process Payment button, the payment process is initiated. After the process finishes, the response can be retrieved by listening to the postMessage 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.

The Response Object

When a HelcimPay.js 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: "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"
}

The data in the response data can be checked for validity, which is covered in HelcimPay.js Validation page.