Initialize a HelcimPay.js checkout session

Before you can render the HelcimPay.js payment modal, you must first perform an API call from your website or applications back-end server to initialize your HelcimPay.js checkout session and get your checkoutToken and secretToken.

📘

Creating your API Access Configuration

All implementations of HelcimPay.js will require an API Access Configuration.

This generates your unique api-token that is used to authenticate your Initialization requests with the Helcim API and sets the permissions for that token to process through HelcimPay.js.

• Create a new API Access Configuration

HelcimPay.js initialize request

The HelcimPay.js initialize request is how you will create your HelcimPay.js checkout session and configure the unique features and functionality for your customers payment experience.

The initialize request creates a checkoutToken that controls a number of parameters that are rendered in the payment modal, including:

• What payment type and payment method the customer is allowed to process payment with, including the amount and currency of the payment.
• Whether the checkout session is linked to an existing customer or invoice, or whether you will use the customerRequest and invoiceRequest objects to create new ones on successful payment.
• Whether you would like to use Helcim Fee Saver to pass on your credit card processing fees, or let your customer pay with ACH payment to reduce your processing costs.
• Whether your customer is allowed to make partial payments for their invoice amount.
• Whether you want to hide existing payment details stored in your Helcim card vault for that customer, or whether you want to set new payment details being used as the customers default moving forward.
• Whether the payment modal will render in full screen or standard modal size, in addition to whether any custom styling elements will be applied to the payment modal for that checkout session.

// Example HelcimPay.js Initialize Request

const options = {
  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', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

🚧

Important note

Your HelcimPay.js Initialization 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 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.js checkout modal and validate any transaction that is processed.

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.

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

HelcimPay.js initialize endpoints

Create a HelcimPay.js checkout session using a single API call to control the features and functionality rendered in the payment modal, using the following endpoint.

• Create a HelcimPay.js Checkout Session