Smart Terminal API

The Smart Terminal API allows you to send transactions to your Smart Terminal devices, directly from your existing third-party point of sale system or software. This gives you the convenience of using your existing system, while taking advantage of our affordable Interchange Plus rates for in-person transactions.

Enable this functionality in your Helcim account settings and send Purchase and Refund transactions from your existing software to your Helcim Smart Terminal devices to take in-person credit and debit payments.

Technical overview

The Smart Terminal API connects your existing third-party point of sale system, to your API mode enabled and registered Smart Terminal devices. The Helcim system facilitates communication between our Smart Terminal API and your devices when requests are sent from your system.

A Smart Terminal in API mode has the same restrictions as standard Smart Terminal devices, allowing for processing only in the core currency for your business location, being CAD for Canadian merchants and USD for US merchants.

Configuration overview

Before connecting to the Smart Terminal API, you will need to create an API token as outlined in our documentation here. This token should be sent in the header of all requests to the Helcim API.

Step 1: Enable Smart Terminal API mode

Before sending payments from your existing third-party software to your Smart Terminal devices, you will need to enable API mode at a global level in your Helcim account settings.

📘
Please note that API mode will apply to all Smart Terminal devices associated with your Helcim account, causing the built-in Helcim point of sale system to no longer be accessible on these devices.

Step 2: Register devices

The next time a user logs into a Smart Terminal device after enabling API mode, it will go through an automatic device registration process with our system. Once this process is completed a unique device code will be displayed on the Smart Terminal's UI, before being ready to accept payments through the Smart Terminal API.

Step 3: Pair devices

Once registered, you can pair available Smart Terminal devices with your existing third-party software, allowing you to send payment requests to specific Smart Terminal devices available on your Helcim account.

Pairing requires storing the unique device codes for each device in your system, then optionally confirming the connection by sending a ping event to the device using the Send a Ping Event endpoint.

Step 4: Enable transaction webhooks

In order to receive transaction responses from payments processed on your Smart Terminal devices, you will need to set up your Helcim webhooks to receive alerts when transactions are processed.

With your webhook enabled, a relevant transaction event is sent to the URL that you subscribed when configuring your webhook settings.

Step 5: Send payment to device

Once your Smart Terminal device is registered and paired with your system, it is ready to receive payment requests received from your existing third-party software via the Smart Terminal API.

Step 6: Process payments on device

When an API mode enabled Smart Terminal receives a payment request, it will prompt the credit / debit flow on the device. The customer may process their transaction in the standard manner for the Smart Terminal, using either tap, or chip + PIN to process the payment.

Once a customer has processed their payment, they may choose to receive a manually printed or emailed copy of the receipt, completed via the Smart Terminal's UI.