Connecting to the Helcim API

Authentication and authorization

To process payments through HelcimPay.js or the Helcim API, we require secure, authenticated communication to protect your account data and processing.

The Helcim API and HelcimPay.js require a valid API token sent in the header of all requests to authenticate with the Helcim system. To generate your unique token, you must log in to the Helcim platform and create an API Access Configuration with your desired access permissions.

Technical header specifications

When making requests to Helcim API endpoints, you must include your API token in the HTTP header. The system validates this token before processing any actions.

Utilize the Connection Test endpoint found in our API References to confirm your integration passes a valid API token in the request header.

curl --request GET \
     --url https://api.helcim.com/v2/connection-test \
     --header 'accept: application/json' \
     --header 'api-token: YOUR_UNIQUE_API_TOKEN'

On successful connection, this endpoint will return a response message indicating that your connection was successful.

{
  "message": "Connected Successfully"
}

If your request contains an invalid token, you will receive an error response indicating that you are unauthorized. Confirm your token is correct before sending a new request.

{
  "errors": "Unauthorized"
}

Creating your configuration

Follow these steps to create your API Access Configuration and generate your secure API token:

Log in to your Helcim account or developer test account
Click All Tools in the top-left corner
Select Integrations under Merchant Tools
Ensure you are on the API Access Configurations page
Click New API Access to get started
Enter a name for your API Access Configuration
Select the checkout integration checkbox if you are integrating with HelcimPay.js and enter the URLs where it will be hosted
Select the appropriate Access Restrictions for your token
Click on Create located in the top right to save the configuration and generate your token

Example API Access Configuration for HelcimPay.js

Configuring your Access Restrictions

Each API Access Configuration can have its own restrictions. The access that you select determines what actions and objects you can control through the Helcim API. You can manage multiple configurations to segment access for different levels of transaction processing or API access.

General: Applies to general objects like Customers, Invoices, Products, and others.
Settings: Applies to settings objects like VT Settings, Customer settings, General settings, and others.
Transaction Processing: Applies to transaction processing through the Payment API and HelcimPay.js.

Transaction processing permission levels

Transaction processing restrictions inherit the capability levels below them. For example, a level 3 token automatically includes level 2 capabilities.

Level	Name	Description	Verify and Preauth	Purchase, Capture and Withdrawal	Refund and Reverse
1	None	Cannot process any transaction type.	❌	❌	❌
2	Auth	Can process verify and preauth transaction types.	✅	❌	❌
3	Positive Transaction	Can processing purchase, capture, and withdrawal transaction types.	✅	✅	❌
4	Admin	Can process refund and reverse transaction types.	✅	✅	✅

We recommend applying the following access restrictions based on your specific implementation:

Helcim API: General: Read & Write | Settings: Read & Write | Transaction Processing: Admin
HelcimPay.js: General: No access | Settings: No access | Transaction Processing: Positive Transaction
Payment Hardware API: General: Read | Settings: Read | Transaction Processing: Admin

⚠️ Security best practices

The following security best practices will ensure that your integration with the Helcim API is protected and secure.

Never expose your token: Obscure your Helcim API token in your back-end environment files. Never make this token visible in client-side code. Bad actors with access to a valid token can process payments and modify your account. Treat your token with the same care as your account password.
Sharing payloads safely: When communicating with Helcim support, obscure all but the last four digits of your API token value in screenshots or payloads.
Handling compromised tokens: If your token is compromised, immediately disable it or generate a new token in your account. Go to All Tools, click Integrations, and select your configuration. Choose the appropriate option from the Actions menu in the top right corner. We also recommend changing your Helcim account passwords and auditing user access.