Integrating with HelcimPay.js

Initialize HelcimPay.js

Before you can call the appendHelcimIframe function to render the payment modal, you must perform an API call to https://api.myhelcim.com/v2/helcim-pay/initialize to initialize HelcimPay.js and get the checkoutToken and secretToken.

📘

Important Note:

When initializing HelcimPay, this request should be made from your website or applications backend server to ensure a secure connection to the Helcim API.

axios.post('https://api.myhelcim.com/v2/helcim-pay/initialize', payload)
  .then(response => console.log(response))
  .catch(err => console.error(err));

When initializing HelcimPay, you must include a paymentType, amount, and currency for the transaction. Additional parameters can be passed in the initialization request to implement things like Helcim Fee Saver or process with Credit Card and ACH Bank Payments.

Read more in HelcimPay.js Initialization and review other body parameters can be sent in your initialize request. Refer to the API Reference documentation for the HelcimPay Initialize request to test it out.

Render the HelcimPay.js modal

Add the HelcimPay.js <script> tag in the HTML header.

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

Call the appendHelcimPayIframe with the checkoutToken

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

Read more in HelcimPay.js Implementation.

Validate the transaction response

Once the customer has processed their transactions, you can listen to the iFrame's event in order to access the responseMessage with the outcome of the transactions, as well as the hash value for the transaction to validate the response.

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'){
      validateResponse(event.data.eventMessage)
        .then(response => console.log(response))
        .catch(err => console.error(err));
    }

  }

});

function validateResponse(eventMessage) {
  const payload = {
    'rawDataResponse': eventMessage.data,
    'checkoutToken': checkoutToken,
    'secretToken': secretToken
  };
  
  return fetch('https://example.example.com/your-endpoint', payload);
}

Validate that the hash from the response is the same as the hashed response data.

public function validateHash(array $rawDataResponse, string $secretToken, string $expectedHash) {
  $encodedData = json_encode($rawDataResponse);
  $hashedResponse = hash('sha256', $encodedData . $secretToken);
  return $hashedResponse === $expectedHash;
}

Read more in HelcimPay.js Validation.