Helcim Logo Support & Tutorials

© Copyright 2006-2018 Helcim Inc.

All Rights Reserved.

Helcim Commerce API »

API Overview

The Helcim Commerce API is a REST (RESTful) API, used to interact with the Helcim Commerce platform. It can be used like a traditional payment gateway API to process credit, debit and EFT/ACH transactions. In addition, it is also be used to interact with the full Helcim Commerce platform, allowing you to add, list, search, generate and manipulate a number of stored objects, such as customers, cards, orders, products and subscriptions.

Our API can be used with any programming language, and we provide coding samples in PHP, Python, Ruby, C#, VB, C++, Java (+ Android), and ObjectiveC (iOS). All requests to our API are made using POST fields, and all responses returned by our API are in XML format. Please note that fields are case-sensitive, with Helcim adhering to lower-camel-casing.

Helcim Commerce API - URL Location
https://secure.myhelcim.com/api/

Security

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 disconnectinued weak connections and ciphers, including SSLv3, TLS1.0 and TLS1.1. A complete list of allowed ciphers can be found on the right of this page.

Authentication

Authentication when using the Helcim Commerce API is required. Authentication is done by providing your Helcim Commerce Account ID and API Token in POST (field formats listed in table below). Helcim does not use HTTP header authentication. You can create as many API accesses as needed, and control the access-rights of each API access (learn more). 

Field Name Type Required Description
accountId Integer Yes The Helcim Commerce account ID.
apiToken String Yes API token used for authentication and access control.

Actions

When making an API call, you must send the desired action, such as processing a payment, adding a customer, etc. This field is required as part of your POST request. All available API actions are listed in the menu to the left of this page.

Field Name Type Required Description
action String Yes The action desired from the API, such as "productView".

Testing

When processing payments, a test field can be set so that transactions are not actually processed through the bank networks, but instead simulated APPROVAL or DECLINE response is generated. Developers may also request for a developer sand-box account, which will process all transactions in TEST mode regardless if the test field is set. Please note that the test setting only applies to payment transactions. Other API calls, such as manipulating objects, will occur regardless of test field.

When testing, please read requirements on using test credit card numbers.

Field Name Type Required Description
test Integer No 1 = test mode, 0 = live, (field not sent = live)

Errors

When a successful connection is established to our API, a standard HTTP status code "200" will be returned, along with the XML response. 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). An example of a XML error response can be found to the right of this page.

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.

Code Samples

API URL Code

https://secure.myhelcim.com/api/

HTML Form HTML

<form name="form1" method="POST" action="https://secure.myhelcim.com/api/">
<input type="text" name="accountId" value="YOUR-ACCOUNT-ID">
<input type="text" name="apiToken" value="YOUR-API-TOKEN">
<input type="text" name="action" value="YOUR-DESIRED-ACTION">
<input type="submit" name="submit" value="CONNECT TO API">
</form>

SSL/TLS Ciphers Code

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

Error Response XML

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