Render the HelcimPay.js payment modal

Render the HelcimPay.js payment modal

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 to access the HelcimPay.js JavaScript.

It should have 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. This JavaScript function can be invoked in different ways on the webpage, such as by a link, or button that uses an onclick event handler.

When invoked, the function will render the iFrame that displays the modal when called with a valid checkoutToken passed as a parameter.

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

// Onclick HTML example
// Requires JavaScript onclick event handler
<a href="#" id="pay-now">Pay Now</a>

// Onclick JavaScript example
document.getElementById('pay-now').addEventListener('click', function(event) {
    event.preventDefault(); // Prevent the default anchor behavior
    appendHelcimPayIframe('checkoutToken');
});

The following table presents the parameters that the function takes as input.

Users can then fill out the form present in the modal with their information and can complete the payment process by clicking on the Process Payment button.

📘

Integrating HelcimPay.js into mobile applications

Because HelcimPay.js uses JavaScript in order to render the payment modal on your website or application, it requires a browser to work. When integrating into mobile applications, your application must utilize a WebView wrapped in a native app.

HelcimPay.js iFrame events

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

The following table summarizes the potential eventStatus values that could be received and when each of these would be triggered.

Listening to iFrame payment events

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

The checkoutToken required to listen to the response is the same used to initialize the HelcimPay.js checkout session.

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);
    }
    
  }
  
});

Transaction response

When a HelcimPay.js credit card payment is processed and the SUCCESS event is emitted from the iFrame, the eventMessage contains a JSON.stringify version of the transaction 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 ACH bank payment is processed and the SUCCESS event is emitted from the iFrame, 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.

Remove the HelcimPay.js iFrame

Once a payment has been processed through HelcimPay.js and the SUCCESS event is received, you will want to destroy the iFrame so that your customers can continue to interact with your system, that was underneath the iFrame element.

To destroy the iFrame, you can call the following HelcimPay.js function. You do not need to pass any parameters to the function, but you will need an element with the same id.

// remove HelcimPay iFrame function
function removeHelcimPayIframe() {
  
 const frame : HTMLElement = document.getElementById(elementId: 'helcimPayIframe');
  
  if(frame instanceof HTMLIframeElement) {
  	frame.remove();
    window.removeEventListener(type: 'message', watchForExit, options: false);
	}
  
}