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.
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
https://secure.myhelcim.com/api/
<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>
EECDH+ECDSA+AESGCM
EECDH+aRSA+AESGCM
EECDH+ECDSA+SHA384
EECDH+ECDSA+SHA256
EECDH+aRSA+SHA384
EECDH+aRSA+SHA256
EECDH
EDH+aRSA
<?xml version="1.0"?>
<message>
<response>0</response>
<responseMessage>Error Message Goes Here</responseMessage>
</message>