| This process requires technical knowledge to implement. You will likely need to work with a developer to complete this setup. |
The Helcim Smart Terminal API offers a powerful way to integrate your existing Point of Sale (POS) system with the Helcim Smart Terminal.
If you use specific industry software or a custom-built POS but want to take advantage of Helcim’s affordable, transparent payment processing, this feature allows your systems to "talk" to each other. This means you can keep your current workflow while benefiting from Helcim's low Interchange Plus rates for in-person payments.
| Are you trying to connect to the Helcim Workstation App? If you are simply trying to connect your terminal to the Helcim POS app on your desktop computer, use this guide instead. |
In this article
What is the Payments Hardware API?
The Smart Terminal API lets your developer connect your current non-Helcim POS system directly to your Helcim Smart Terminal hardware.
In this setup, your third-party software acts as the "controller". When you initiate a sale or order on your custom POS screen, it securely sends a message via the cloud to your Helcim Smart Terminal and Card Reader Gen3, telling it to display the payment prompt.
Paired mode vs. Standalone mode
To use your Smart Terminal with a third-party POS or custom API integration, the terminal must be placed into Paired mode. This tells the hardware to listen exclusively for instructions coming from your POS backend.
| If your terminal is switched to Standalone mode, it operates as an independent checkout tool and will automatically reject incoming API requests from your custom software. |
How the Smart Terminal API works
Setting up the integration involves some developer configuration. Because this requires technical adjustments, you will likely need to work alongside a software developer to get things running smoothly.
Step 1: Enable API permissions with Helcim Support
To maintain account security and prevent accidental interruptions. Third-party POS configurations need to start with creating a API token. Then use the Switch button on the terminal to switch to Paired mode to retrieve the device code.
Step 2: Register your hardware
Now you need to register each physical terminal:
Turn on your Smart Terminal and ensure it is connected to a secure Wi-Fi network.
Tap More in the bottom right corner of the Helcim app on your device, and select Log out.
Log back in to the device using your merchant credentials.
This fresh login automatically registers the hardware with our cloud infrastructure and generates a unique, device-specific pairing code directly on the terminal screen.
Step 3: Link your POS system
Provide the unique device codes generated by your terminals to your software developer. They will input these keys into your third-party POS backend to link your software directly to those specific terminals, ensuring secure, encrypted communication.
Step 4: Enable transaction webhooks
Have your developer set up Helcim webhooks. Webhooks send instant, real-time alerts from Helcim back to your POS system whenever a transaction is approved, declined, or voided, keeping your business records perfectly in sync.
Step 5: Send payment requests
With everything linked and webhooks configured, you are ready to process sales! Initiating a payment on your custom POS will automatically light up the terminal, allowing your customer to tap, insert, or enter their PIN to finish the transaction.
Next steps
For Developers: For detailed endpoints, technical specifications, and JSON payload examples, please visit our Smart Terminal API.
For Merchants: If you are unsure whether an API integration is the right fit for your counter space or business model, contact Helcim support, we are happy to map out your workflows with you.
FAQs
Does pairing mode work with Helcim Fee-Saver?
Yes! Pairing mode is fully compatible with Helcim Fee-Saver. The Smart Terminal will automatically display the surcharge screen when your customer is ready to pay.
Will my existing Smart Terminal settings still apply?
Yep! Any Smart Terminal set to pairing mode will keep its previous settings, like auto-printing receipts or printing merchant copies.
What if I only want pairing mode on some of my Smart Terminal devices?
Pairing mode applies to all Smart Terminals linked to your Helcim account.
What happens when I disable pairing mode?
Disabling pairing mode reverts the Smart Terminal to its standard point-of-sale mode. Any payment requests from your POS system will be rejected. Check out our Errors and Error Handling documentation for more details on potential errors.
Will my Smart Terminal devices keep their device code if I disable and re-enable pairing mode?
Great question! Smart Terminals enabled for pairing store their registration code in the device hardware settings. So, if you temporarily disable and then re-enable pairing mode, the device will keep its existing code and continue to work.