Implementing your Helcim.js

Before you configure any Helcim.js Configurations or API Access Configurations in your Helcim account, you will need to decide on how you would like to implement Helcim.js in your website or application.

Recommended Helcim.js Implementation

To ensure enhanced security for your Helcim.js integration, we recommend utilizing Helcim.js to complete a Verify transaction and tokenize card details, then process your Purchase transaction with the returned cardToken through the Process Purchase Transaction endpoint in the Payment API.

Combining Helcim.js with the Payment API in this manner, creates a secondary layer of protection for your Purchase transactions. These Payment API requests require a valid API token, that is stored securely in your system and sent in the header of your subsequent Payment API requests. This ensures only authorized Purchase transactions are processed by the Helcim system for your account.

Helcim.js Implementation Flows

The steps below outline the potential integration and transaction flows created by different Helcim.js implementations, in addition to the required configurations and API endpoints to facilitate that flow.

Card Verify through Helcim.js + Purchase through Payment API

This integration flow requires you to implement Helcim.js in your payment flow and also integrate your website or application to the Payment API. This flow provides extra security for your integration when processing Purchase transactions, by leveraging the additional security features of the Payment API.

A successful Verify through Helcim.js will return a cardToken to you in the transaction response. This cardToken can be stored in your system and used to through the Process Purchase Transaction endpoint in the Payment API, so long as the card remains valid.

1. Create a Helcim.js Configuration with Transaction Type set to Card Verify (Tokenize Only).
2. Create an API Access Configuration to process your Purchase requests through the Payment API.
3. Implement Helcim.js in the HTML of your website or application.
4. Integrate your website or application with the Process Purchase Transaction endpoint in the Payment API.

Card Purchase through Helcim.js

This integration flow requires you to only implement Helcim.js in your payment flow. When processing Purchase transactions directly through Helcim.js, we strongly recommend validating transaction amounts using the Amount Hashing functions outlined in our integration documentation.

1. Create a Helcim.js Configuration with Transaction Type set to Card Purchase.
2. Implement Helcim.js in the HTML of your website or application.

Card Pre-Authorization through Helcim.js + Capture through Payment API

This integration flow requires you to implement Helcim.js in your payment flow and also integrate your website or application to the Payment API. This flow provides extra security for your integration when processing Pre-Authorized transactions, by leveraging the additional security features of the Payment API when Capturing those payments.

1. Create a Helcim.js Configuration with Transaction Type set to Card Preauth.
2. Create an API Access Configuration.
3. Implement Helcim.js in the HTML of your website or application.
4. Integrate your website or application with the Process Capture Transaction endpoint in the Payment API.

📘

Manually Capturing Payments

In the event that you would like to manually Capture payments through the Payments user interface in your Helcim account, then Step 2 and Step 4 in this integration flow are no longer required.

Helcim.js transactions and the Payment API

The Helcim System has a number of backend payment systems that facilitate the processing and settlement of credit card transactions with their own unique id values. Completing subsequent actions through the Payment API expects a different transactionId value than the one returned by Helcim.js.

Retrieving the updated V2 API transactionId value would be required if you want to Refund or Reverse Purchase transactions processed through Helcim.js, capture any Helcim.js Pre-Authorize Transactions through the Payment API, or retrieve any Verify payments through the Card Transaction API.

To retrieve this value, we recommend calling the Collect Card Transaction endpoint with relevant query parameters to filter returned transactions down to the correct one. This could include a combination of values returned by Helcim.js, such as the date, cardHolderName, amount and cardToken for the transaction.

Based on this the V2 API will return a transaction object with a transactionId that can be used through all Payment API endpoints.

 {
    "transactionId": 25133280,
    "dateCreated": "2024-04-24 16:14:41",
    "cardBatchId": 3509924,
    "status": "APPROVED",
    "user": "Helcim System",
    "type": "purchase",
    "amount": 456,
    "currency": "CAD",
    "avsResponse": "X",
    "cvvResponse": "",
    "cardType": "MC",
    "approvalCode": "T3E3ST",
    "cardToken": "5c92996b7d573c1b15fc6e",
    "cardNumber": "5454545454",
    "cardHolderName": "Jessica Smith",
    "customerCode": "CST123457143",
    "invoiceNumber": "INV8792466",
    "warning": ""
  }