The Helcim API and HelcimPay.js require a valid api-token sent in the header of all requests to authenticate with the Helcim system.

A merchant or developer needs to log in to the Helcim platform and create their unique api-token for their account. They must also set the permissions level for that token to determine what functions can be undertaken when sending requests to the Helcim API.

API tokens should be protected by merchants and developers, as having access to a valid token gives a bad actor the potential to process payments and make modifications to a merchant’s account. This is similar to why merchants should protect their password and not share it with anyone.

Creating your API Access Configuration

As part of the API authentication fields, you need to create an API access token in order to authenticate and gain access to the Helcim API. The API token is used for requests to the Helcim API and HelcimPay.

To get started:

• Log in to your Helcim Account.
• Click on All Tools and then on the Integrations.
• Select API Access Configuration from the left menu.
• Click on New API Access to get started.

• Enter a name for your API Access Configuration.

• Select the appropriate Access Permissions for your API token.
• Click Create located on the top right of the page to save your configuration and generate your API token.

👍

Legacy API tokens:

Please note that legacy Helcim API tokens cannot be used for Helcim API V2 endpoints. Depending on your unique integration, you can use a combination of legacy endpoints and V2 endpoints, however please note that legacy endpoints are now deprecated.

Configuring your API Access Permissions

Each API access token that you create will have its own permissions and the access you select for your API configuration should depend on what you intend to do through the Helcim API. Review our suggested API permissions for common use cases below.

• General permissions will apply to general objects like Customer, Order, Products, and Others
• Settings permissions will apply to settings objects like VT Settings, Customer Settings, General Settings, and Others
• Transaction Processing
  • None - cannot process any type of transaction
  • Auth - for processing Verify and Preauth transactions
  • Positive Transaction - for processing Purchase and Capture
  • Admin - for processing Reversal, Refund

Transaction Processing permissions inherit the lower permissions levels when selected.

Recommended API Access Permissions

📘

HelcimPay.js Permissions:

Please note that you cannot process Refund Transactions through HelcimPay.js. If you intend to use the same API token for requests to the Helcim Payment API through the Process Refund Transaction endpoint, then you would want to set Transaction Processing to Admin.

Testing Your API Token

In order to test your API token is valid you can utilize the API Reference to test connectivity to the Helcim API. 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 API token, you will receive an error response from the API indicating that you are unauthorized to make the request. Please confirm that your API token is correct and valid for the endpoint you are calling before submitting a new request.

{
  "errors": "Unauthorized"
}

API Token Best Practices

We recommend obscuring your Helcim API token in your integrations back-end environment files and never making this token visible in your client side code.

When communicating with Helcim support and sending screenshots of code, or API requests and responses, we encourage merchants and developers to obscure all but the last 4 digits of their API tokens.

Compromised API Tokens

If a merchant has their API token compromised, they should either immediately disable it in the Helcim account settings, or generate a new token. We would also recommend changing the passwords to access your Helcim account and ensure that only active and valid employees and developers have user access to the account.

To deactivate or generate a new token for your API Access Configuration, go to All Tools, Integrations and then select the relevant configuration that you would like to modify. You can select the appropriate option from the Actions menu after selecting that configuration.

Authentication Errors

Unauthorized

This status 401 error response will be returned if you have attempted a request with an invalid or inactive api-token. Confirm your api-token is correct and active, in the Integrations section of your Helcim account, then attempt your request again.

{
    "errors": "Unauthorized"
}

No Access Permission

You have attempted a request that requires permissions that the API token passed in the request is not allowed to complete. Update your token permissions in the Integrations section of your Helcim account and attempt your request again.

{
    "errors": "No access permission"
}