HelcimPay.js Validation

To ensure the integrity of the HelcimPay.js transaction response, it can be validated by comparing the hash returned in the response, with your hash generated from combining the response data and the secret token.

Access the HelcimPay.js 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.

// Example transaction response
data: {
  "transactionId": "20163175",
  "dateCreated": "2023-07-17 10:34:35",
  "cardBatchId": "2915466",
  "status": "APPROVED",
  "type": "purchase",
  "amount": "15.45",
  "currency": "CAD",
  "avsResponse": "X",
  "cvvResponse": "",
  "approvalCode": "T3E5ST",
  "cardToken": "27128ae9440a0b47e2a068",
  "cardNumber": "4000000028",
  "cardHolderName": "Test",
  "customerCode": "CST1049",
  "invoiceNumber": "INV001045",
  "warning": ""
},
hash: "dbcb570cca52c38d597941adbed03f01be78c43cba89048722925b2f168226a9" // Hash returned by Helcim

This data can be sent from your front-end to your secure back-end in order to complete the validation.

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.com/your-endpoint', payload);
}

Generate and compare your transaction response hash

To generate your hash you will JSON encode the transaction response data, append it with the secretToken, then hash them using a secure sha-256 algorithm.

$secretToken = 'sample-secret';
$jsonEncodedData = '{
  "transactionId": "20163175",
  "dateCreated": "2023-07-17 10:34:35",
  "cardBatchId": "2915466",
  "status": "APPROVED",
  "type": "purchase",
  "amount": "15.45",
  "currency": "CAD",
  "avsResponse": "X",
  "cvvResponse": "",
  "approvalCode": "T3E5ST",
  "cardToken": "27128ae9440a0b47e2a068",
  "cardNumber": "4000000028",
  "cardHolderName": "Test",
  "customerCode": "CST1049",
  "invoiceNumber": "INV001045",
  "warning": ""
}';
$cleanedJsonEncodedData = json_encode(json_decode($jsonEncodedData, true));
$expectedHash = hash('sha256', $cleanedJsonEncodedData . $secretToken); // dbcb570cca52c38d597941adbed03f01be78c43cba89048722925b2f168226a9

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

The hash value returned from your validateHash() function should match the hash value returned in the transaction response from Helcim.

data: {
  "transactionId": "20163175",
  "dateCreated": "2023-07-17 10:34:35",
  "cardBatchId": "2915466",
  "status": "APPROVED",
  "type": "purchase",
  "amount": "15.45",
  "currency": "CAD",
  "avsResponse": "X",
  "cvvResponse": "",
  "approvalCode": "T3E5ST",
  "cardToken": "27128ae9440a0b47e2a068",
  "cardNumber": "4000000028",
  "cardHolderName": "Test",
  "customerCode": "CST1049",
  "invoiceNumber": "INV001045",
  "warning": ""
},
hash: "dbcb570cca52c38d597941adbed03f01be78c43cba89048722925b2f168226a9"

Example hash implementation:

$secretToken = 'sample-secret';
$jsonEncodedData = '{
  "transactionId": "20163175",
  "dateCreated": "2023-07-17 10:34:35",
  "cardBatchId": "2915466",
  "status": "APPROVED",
  "type": "purchase",
  "amount": "15.45",
  "currency": "CAD",
  "avsResponse": "X",
  "cvvResponse": "",
  "approvalCode": "T3E5ST",
  "cardToken": "27128ae9440a0b47e2a068",
  "cardNumber": "4000000028",
  "cardHolderName": "Test",
  "customerCode": "CST1049",
  "invoiceNumber": "INV001045",
  "warning": ""
}';
$cleanedJsonEncodedData = json_encode(json_decode($jsonEncodedData, true));
hash('sha256', $cleanedJsonEncodedData . $secretToken); // dbcb570cca52c38d597941adbed03f01be78c43cba89048722925b2f168226a9