You can use the Helcim API to integrate payments and other aspects of the Helcim system into your application or website. The API can also be used to retrieve, create, or modify a number of data objects beyond payments, including customers, card batches, invoices, and transactions.

API Overview

The Helcim API is grouped into several subcategories as outlined in our API reference documentation. Each of these have a different use case and allow you to execute different functions in the Helcim system.

• The Payment API endpoints enables you to process credit card payments through your website or application. Payment types include, Purchase, Preauthorization, Capture, Verify, Refund, and Reverse.
• The ACH Payment API endpoints enable you to process ACH bank payments through your website or application, as well as retrieve and modify a number of objects related to ACH bank payments. Payment functions include, Withdraw, Refund, Void, or Cancel.
• The Smart Terminal API enables you to process in-person credit card or debit transactions through your existing third-party point of sale system, connected to a Helcim Smart Terminal. Payment types include, Purchase and Debit Refund transactions.
• The Recurring API enables you to set up recurring payment plans and subscribe customers to those plans through your website or existing software. You can create, retrieve, update, and delete a range of payment plan, subscription, and add-on objects in the Helcim system.
• The Invoice API endpoints enable you to create, retrieve, and update invoices. API functions include Get invoice, Get invoices, Create invoice and Update invoice.
• The Customer API endpoints enable you to create, retrieve, and update customers and view and update customer payment information. API functions include Get customer and Get customers, Create customer, Update customer, as well as functions to get existing card and bank account information linked to customer objects.
• The Card Batch API endpoints enable you to retrieve and settle their Credit Card Batches. API functions include Get Card Batches, Get Card Batch, and Settle an Open Card Batch.
• The Card Transaction API endpoints enable you to view previous payment transactions. API functions include Collects up to 1000 Card Transactions and Get Card Transaction by id.

Let's get started!

Technical Overview

The newest version of the Helcim API brings our API endpoints up to a modern REST standard that is familiar to developers.

When using the Helcim API there are some important technical points to take into consideration. Outlined below we'll cover some of these points and where appropriate we will link to relevant documentation to help you integrate with Helcim smoothly.

• Only requests authenticated by a valid Helcim API token will be accepted by any API endpoint.
• The Helcim API will only accept requests sent from your website or applications secure back-end server.

API Message Format

The Helcim API consumes requests in JSON with all required information in the request header and body and returns a JSON object as a response.

When a successful connection is established, a standard status 200 HTTP code will be returned for successful requests. You should not assume that a status 200 code indicates that the requested action was successfully performed; instead you should refer to the response object for more information on the outcome of the request.

Request Header

Only authorized users may submit requests to Helcim API endpoints. In order to authenticate with our service, send your api-token in the header of your request and ensure that the permissions for your respective API Access Configuration allow for the request you are making.

• Request headers should also include accept and 'content-type' parameters set to 'application/json'.
• Requests sent to Payment API endpoints also require an idempotency-key value to be sent.

  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    'api-token': 'YOUR_API_TOKEN'
  }

Request Body

Body parameters should be sent in your request in JSON format. Each respective endpoint has unique required and optional body parameters to be sent in your request.

Review our API reference documentation to see what information is required for the endpoint that you are calling, or review the specific API guides for more detailed information about specific requests.

Responses

The API will return a response as a JSON object for your website or application to consume, with relevant data objects or an errors object that outlines any errors that occurred. Some possible response types from the API include:

• A single object
• A transaction response object
• An array of objects
• An array of errors

// Example transaction response object

{
  "transactionId": 25557533,
  "dateCreated": "2024-05-13 12:49:06",
  "cardBatchId": 3559552,
  "status": "APPROVAL",
  "user": "Helcim System",
  "type": "purchase",
  "amount": 100.99,
  "currency": "CAD",
  "avsResponse": "X",
  "cvvResponse": "",
  "cardType": "MC",
  "approvalCode": "T7E8ST",
  "cardToken": "2f7c46a9aa15c52da72380",
  "cardNumber": "5454545454",
  "cardHolderName": "John Doe",
  "customerCode": "CST1035",
  "invoiceNumber": "INV1263",
  "warning": ""
}

HTTP Response Codes

The Helcim API will return a response code appropriate to the outcome of the request and will follow REST best practices when it comes to HTTP response codes.

API Rate Limits

In order to protect the Helcim system and maintain service quality and availability for our merchants, the Helcim API has rate limits on requests to our endpoints.

These rate limits restrict the number of API calls a user can make to our API in a given time period and multiple API tokens on the same Helcim account share the same limit. The Helcim API will check the total number of requests in the last 60 seconds or 60 minutes from the time of request, to ensure that the total number of requests does not exceed the below limits.

• Concurrent Limit: 5 calls in progress at one time.
• Minute Limit: 100 calls per minute.
• Hourly Limit: 3000 calls per hour.

If you exceed the rate limits outlined in this documentation, the Helcim API will return an error response with HTTP code 429 - Too Many Requests. You will need to wait until your limits have reset before making further calls to the Helcim API.

Headers

The remaining requests for each rate limit are included in the header of the Helcim API response to your request.

minute-limit-remaining: 99
hour-limit-remaining: 2999

SSL / TLS Ciphers

Helcim API calls are made over HTTPS (port 443) and the connection is secured using an SSL certificate with a SHA256 key. To adhere to strong PCI-DSS standards we've disconnected weak connections and ciphers, including SSLv3, TLS1.0 and TLS1.1.

Below is a complete list of allowed ciphers:

EECDH+ECDSA+AESGCM
EECDH+aRSA+AESGCM
EECDH+ECDSA+SHA384
EECDH+ECDSA+SHA256
EECDH+aRSA+SHA384
EECDH+aRSA+SHA256
EECDH
EDH+aRSA

Understanding API Errors

When a request to the Helcim API results in an error response, the respective endpoint will return a response with an 'errors' object containing any relevant error messages. These will be returned with an appropriate HTTP response code in order for you to handle the error within your integration appropriately.

The Helcim API can return one or more errors within the same errors object, and each error may require a different resolution before submitting your request again. The key of each error message within the object will often correlate to the field within the request where the error originated, while the value will provide more information on why the error occurred.

Depending on the root cause of Helcim API errors, you may need to resolve these by changing Helcim account settings, or updating the information sent in the header or body of your API request.