Getting started with the Helcim API

Welcome to the Helcim API!

You can use the Helcim API to integrate payments into your application or website. The API can also be used to list, view, create or modify a large number of data objects, including items in your product catalog, customers, orders, and transactions. There are more than 80 different API actions that developers can perform. Let's get started!

API Message Format

The Helcim API consumes POST parameters in the message body, and returns XML.

Authentication

To keep your Helcim account secure, any API access to your account must be authenticated using a API access token.

Field NameFormatDescription
account-idIntegerYour Helcim account ID. Learn how to find your Helcim account ID.
api-tokenStringYour Helcim API access token. Learn how to create an API access token.

Both of these fields are required, and should be set as part of your HTTP header authentication when making any API request. (optional) These fields can also be sent camelCase in POST instead of HTTP header.

Security & TLS Ciphers

API calls are made over HTTPS (port 443), and the connection is secured using an SSL certificate with a SHA256 key. To adhere to the 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 successful connection is established to our API, a standard HTTP status code "200" will be returned, along with the XML response. You should not assume that a "200" status code indicates that the requested action was successfully performed; instead you should refer to the xml status.

XML Field NameTypeDescription
message-XML Structure
responseInteger1 = success
0 = failure
responseMessageStringThe response message, usually containing the error, such as a missing or invalid field.

Below are example success and error responses from the Helcim API:

<?xml version="1.0"?>
<message>
    <response>1</response>
    <responseMessage>Connection Successful</responseMessage>
</message>
<?xml version="1.0"?>
<message>
    <response>0</response>
    <responseMessage>Error Message Goes Here</responseMessage>
</message>

Most commonly, a "400" HTTP status code is likely due to your server or app being unable to establish a proper SSL/TLS handshake with our web-server. You may need to update the certificates and ciphers installed on your server.

HTTP Status CodeMessageDescription
200OKThe connection to our API was successful.
400Bad RequestThe server cannot process your request. The XML response will contain the desired information requested, or an error with the structure of the API request (such as missing or invalid request fields).