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.

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.

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.