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 Name

Format

Description

account-id

Integer

Your Helcim account ID. Learn how to find your Helcim account ID.

api-token

String

Your 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 Name

Type

Description

message

XML Structure

response

Integer

1 = success
0 = failure

responseMessage

String

The 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 Code

Message

Description

200

OK

The connection to our API was successful.

400

Bad Request

The 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).