HelcimPay.js Implementation

🚧

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

Example implementation:

<a href="javascript: appendHelcimPayIframe(checkoutToken, false)">
  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 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.

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.