HelcimPay.js Initialization

This reference outlines the steps for initializing a HelcimPay.js checkout session.

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 a HelcimPay.js checkout session and get your checkoutToken and secretToken.

🚧

Important Note:

When initializing HelcimPay, this request should be made from your website or applications secure back-end server. Attempting to send your HelcimPay.js initialize request from your front-end or client side code, will result in a Cross-Origin Resource Sharing (CORS) error.

HelcimPay.js Initialize Request

When initializing HelcimPay, you must include required body parameters for the paymentType, amount, and currency of the transaction.

const payload = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'api-token': 'YOUR_API_TOKEN',
    'content-type': 'application/json'
  },
  body: JSON.stringify({paymentType: 'purchase', amount: 100, currency: 'CAD'})
};

fetch('https://api.helcim.com/v2/helcim-pay/initialize', payload)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.helcim.com/v2/helcim-pay/initialize",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'paymentType' => 'purchase',
    'amount' => 100,
    'currency' => 'CAD'
  ]),
  CURLOPT_HTTPHEADER => [
    "accept: application/json",
    "api-token: YOUR_API_TOKEN",
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import sdk from '@api/helcimdevdocs';

sdk.checkoutInit({
  paymentType: 'purchase',
  amount: 100,
  currency: 'CAD'
}, {
  'api-token': 'YOUR_API_TOKEN'
})
  .then(({ data }) => console.log(data))
  .catch(err => console.error(err));

📘

Create a HelcimPay.js checkout session

You can use the API Reference documentation for the HelcimPay Initialize endpoint to generate a request in a range of different programming languages.

The table below outlines the required headers for a successful initialization request.

PropertyTypeNecessityDescription
api-tokenStringRequiredYour unique API token generated by creating an API Access Configuration.

The table below outlines the required payload for a successful initialization request.

Optional parameters can be passed in the initialization request to implement additional functionality, like Helcim Fee-Saver, what payment methods are available, or whether the transaction should be associated with an existing Customer or Invoice in the Helcim System.

PropertyTypeNecessityDescription
paymentTypeStringRequiredThe type of transaction of you would like to process: purchase | verify | preauth
amountNumberRequiredThe final amount of the transaction to process.
currencyStringRequiredThe currency of which the transaction will be processed: CAD | USD
customerCodeStringOptionalAn existing Helcim customer’s code you want to tie the transaction with. If this field is not present, a new customer will be created and linked to the transaction using card holder information entered during processing.
invoiceNumberStringOptionalAn existing Helcim due invoice number you want to process. If this field is not present, a new invoice will be created and linked to the transaction.
paymentMethodStringOptionalThe payment method that you are allowing the customer to use to pay for the amount: cc | ach | cc-ach. When using Helcim Fee-Saver this must be cc-ach.
allowPartialNumberOptionalPassing a value of 1 will determine whether the partial payment UI will be displayed to the customer in the HelcimPay modal. An existing due invoice must be linked to the checkout session by passing the invoiceNumber parameter.
hasConvenienceFeeNumberOptionalPassing a value of 1 will determine whether Helcim Fee Saver will be available to the customer in the HelcimPay modal, allowing for the addition of a convenience fee to cover processing fees through Credit Card.
taxAmountNumberOptionalPassing a dollar amount for tax, to 2 decimal places, is used by Helcim to facilitate lower per transaction rates by enabling Level 2 processing. The Helcim payments system will take care of the rest.

This taxAmount value is inclusive in the amount value initialized and does not get added to the amount or any subsequent invoice created by HelcimPay.js.

HelcimPay.js Initialize Response

The Helcim system will respond to a successful initialize request with a JSON object containing a checkoutToken and secretToken that can be used to render the HelcimPay checkout modal and validate any transaction that is processed.

{
  "secretToken": "1d4b6437a8aabfe4b0ed93",
  "checkoutToken": "49702e8e38d5db9226b54f"
}

The checkoutToken and secretToken returned by the HelcimPay.js initialize endpoint are only valid for 60 minutes after being returned. After this they expire and you would need to call the initialization endpoint to receive new tokens to render the HelcimPay.js modal.

The table below details the response payload received from the API upon successful execution.

PropertyTypeDescription
checkoutTokenStringThe checkoutToken is the key to displaying the HelcimPay.js modal using the appendHelcimIframe function. This token ensures a secure connection between the cardholder’s web browser and the Helcim Payment API endpoint. Please note, the checkout token is a unique value for each payment instance, and it expires after 60 minutes, or once the transaction is processed. Having unique and recent checkout tokens reduces the likelihood that an unauthorized payment is processed.
secretTokenStringThe secretToken is used for validation purposes after a transaction has been processed successfully. This token, along with transaction data in the response are used to create a hash. You can use this to verify that the data in the transaction response is valid and has not been tampered with.