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.

HTTP Status Code	Message	Description
200	Ok	The request succeeded. This response is a generic response for successful requests, including getting or updating a resource.
201	Created	A new resource was successfully created and is typically provided in response to a POST request to create a new resource.
202	Accepted	The request has been received but not yet acted upon and is returned when a request is queued for later processing.
204	No Content	The request was successful, but the Helcim API has no data to respond with, such as when a resource is successfully deleted.
400	Bad Request	The server cannot process your request. The JSON response will contain the desired information requested, or an error with the structure of the API request (such as missing or invalid request fields).
401	Unauthorized	There are missing or invalid credentials in the request. Either no API token was provided, or an incorrect API token was provided, such as providing a legacy token for a V2 endpoint.
403	Forbidden	The given credentials are not permitted for this action. The permissions associated with the API token do not allow for the requested action and should be updated before resending the request.
405	Method Not Allowed	The resource or action exists, but is not supported with the given request method, such as attempting to delete a resource that does not allow for this.
409	Conflict	The request received conflicts with a previous request accepted by the APOI, often caused by an idempotency key that has been assigned to an existing successful transaction.
429	Too Many Requests	The user has sent too many requests in a given amount of time. For more information on rate limiting, review our Rate Limits documentation.
500	Internal Server Error	A fatal error in logic has impacted the ability of the API to provide a well structured response. Internal server errors can be reported to Helcim support for further investigation.
522	Service Unavailable	Services are down, impacting our ability to provide a response at this time.