VibeFox Helcim for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

PHP: 8.0 or later.

HTTPS and PCI DSS: card details are entered on your checkout and sent from your server to Helcim. They are never stored or logged, but they pass through your server, so your store needs an SSL certificate for the checkout and your hosting must meet PCI DSS (SAQ D).

Currency: Helcim processes CAD and USD. The payment method is shown only when the checkout currency is one of the Account currencies set in the extension.

Helcim account: a Helcim merchant account in Canada or the United States and an API token with transaction processing rights (see Configuration). A Helcim test (developer) account is optional for testing.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_helcim_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_helcim_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_helcim_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Helcim Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the page and click Activate (see License key).

4. In Helcim open All Tools > Integrations > API Access Configuration, create an API access with transaction processing rights (purchases, pre-authorizations, captures, refunds) and copy its token.

5. Paste the token into Live API token, and the token of your Helcim test account into Test API token if you have one.

6. Choose the Transaction type and the Account currencies, turn on Enable / Disable and click Save. To test first, turn on Test mode and pay with your test account; then turn it off.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_helcim_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Helcim Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the API tokens and the payment settings as in steps 3 to 6 for OpenCart 3. The settings page and its fields are the same in both versions.

A new install starts with the payment method turned off and test mode off.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page warns you when the default currency of your store is not one of the Account currencies (Helcim is then offered only for orders in an allowed currency), and, while the payment method is enabled, when the API token of the current mode is empty (the payment method is then hidden at checkout). Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty (at most 128 characters), Sort Order must be a whole number, Total a number, 0 or greater, and every order status must exist. If anything is wrong, nothing is saved and the page lists the errors.

Helcim

Enable / Disable: Enable Helcim Gateway turns the payment method on or off. Default: off.

Title: the payment method title shown at checkout. It is also the payment method name stored in the order. Default: Credit card (Helcim). Required.

Description: the text shown to the customer at the Confirm Order step, above the card form. Default: Pay securely with your credit card.

Sort Order: the position of the payment method at checkout. Leave it empty or enter a whole number.

Geo Zone: offer the card form only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before the payment method is offered. Leave it empty to offer it for any total.

API credentials

In Helcim go to All Tools > Integrations > API Access Configuration, create an API access and copy its token. Give it transaction processing rights for purchases, pre-authorizations, captures and refunds. Helcim test accounts use the same API address as live accounts, so test mode simply uses the token of your Helcim test account. The section links to the Helcim API documentation.

Live API token: the API token of your live Helcim account. Used when test mode is off.

Test mode: uses the Test API token (Helcim test account). Payments, captures and refunds go to your Helcim test account, and customers see a test mode notice. Captures and refunds of an order always use the token of the mode the order was paid in. Default: off.

Test API token: the API token of your Helcim test (developer) account. Used when test mode is on.

Saved tokens are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it. To remove a saved token, tick Clear the saved token on save under the field and click Save.

Payment

Transaction type: how the card is charged.

Account currencies: the currencies your Helcim account can process. Orders are always charged in the order currency. The payment method is hidden at checkout for other currencies.

Orders

The order is created at the Confirm Order step without a status (a missing order) and gets a status only after Helcim has approved the card. Each field lists your OpenCart order statuses.

Order Status After Payment: the card was charged (purchase, or the capture of a pre-authorization). Default: Processing.

Authorized Status: pre-authorization: the funds are only held, not charged yet. Capture them with Capture payment in the order tab. Default: Pending, because OpenCart has no On hold status.

On Hold (Review) Status: the Helcim answer does not match the order (partial approval, another currency, no transaction ID, or the order total differs from the charge). Verify the transaction in Helcim before fulfilling; a note explains why. Default: Pending. You can create your own statuses in System > Localisation > Order Statuses to tell the authorized and review orders apart.

Canceled Status: an uncaptured pre-authorization was released from the order tab (the customer was not charged). Default: Canceled.

Refunded Status: set after the payment is fully refunded from the order tab. Default: Refunded.

Advanced

Debug log: writes API requests and responses to wc_hlg_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web. Card numbers are reduced to the last 4 digits. CVC, expiry, tokens, names, addresses, e-mails and IP addresses are never logged. Errors (declined or failed payments, API errors, failed captures and refunds) are always logged, even when this is off. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete data on uninstall: when on, uninstalling the extension removes the gateway settings and its log files. The Helcim transactions and refunds always stay, so orders paid before can still be captured and refunded after a re-install. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. API tokens are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved API tokens are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Credit card (Helcim)). At the Confirm Order step the customer sees a card icon, your description and the form with Card Number, Expiry (MM/YY), CVC and Cardholder Name. In test mode the form shows TEST MODE — payments go to a Helcim test account, no real charges are made. OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension checks the card number checksum, that the expiry date is valid and not in the past, that the CVC has 3 or 4 digits and that the name is filled in. Errors are shown above the form and nothing is sent to Helcim.

On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options. The card form then appears in the order confirmation block at the bottom of the checkout page, above the Confirm Order button. By default OpenCart 4 does not ask for a payment address; the extension then sends the shipping address to Helcim for address verification, with the cardholder name.

Your server then sends the card to Helcim as a purchase or a pre-authorization for the order total in the order currency. The cardholder name, payment address, phone and e-mail are sent for address verification. The payment shows in Helcim with an invoice number made of the order number, -OC and a short code. Helcim answers in the same request. The order gets its status only after Helcim approves the transaction, the standard OpenCart way, with the usual order e-mails and stock update. The cart is emptied at once and the customer lands on the OpenCart order success page.

Only one payment attempt per cart runs at a time, and a cart that is already paid is never charged again, even when OpenCart has created a new order for it in the meantime (OpenCart 3 creates a new order every time the Confirm Order step is shown; on OpenCart 4 an earlier order or a second browser tab can still hold the same cart). OpenCart 4 keeps one order for the checkout and updates it, so after a declined card the customer pays the same order. If that order was closed meanwhile (for example you cancelled it), or it is already paid and the cart now holds a new purchase, Confirm Order takes the customer back to the checkout page with Your previous order is already closed (cancelled or refunded by the store) or paid for another cart. Please confirm the order again: the cart will be paid with a new order. above it, and the next Confirm Order pays a new order of the cart. A change of the cart, including a new quantity, counts as a new cart that needs its own payment. Every attempt uses an idempotency key. If Helcim does not answer, the order stays without a status, and a retry within 5 minutes returns the original Helcim result instead of charging the card twice. If the payment was approved but the order status could not be set, the next attempt of the same cart sets it without charging the card again.

Messages the customer may see above the form: Your card was declined. Please check the card details or use another card. when Helcim declines; Payment failed: with Helcim's reason for other rejected requests; We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card. when Helcim does not answer; This payment method is temporarily unavailable. Please choose another payment method. when the API token is rejected; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. on a double submit; Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. when the payment was approved but the order status could not be set. The customer stays at the Confirm Order step with the same cart. Technical details go to the log.

The extension does not use HelcimPay.js or Helcim.js, so card details pass through your server. It has no saved cards, subscriptions, ACH or bank payments, Apple Pay, Google Pay or 3-D Secure, and no Helcim webhooks.

Orders and refunds

Order statuses

No status (missing order): the card was declined, Helcim did not answer, or the customer has not paid yet. Declines and errors are written to the log and added as notes. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): a purchase was approved, or a pre-authorization was captured. A note shows the transaction ID, approval code, card type, last 4 digits and mode.

Authorized Status (default Pending): a pre-authorization was approved. The funds are only held. Capture them or release them with a full refund.

On Hold (Review) Status (default Pending): Helcim approved a transaction, but the amount, currency or transaction ID in its answer does not match the order, for example after a partial approval or when the order total changed during the payment. The note says Helcim response verification FAILED. Check the transaction in Helcim before fulfilling.

Refunded Status (default Refunded): the payment was fully refunded through the extension.

Canceled Status (default Canceled): an uncaptured pre-authorization was released. The customer was not charged.

Notes are entries in the order History that the customer does not see.

VibeFox Helcim Gateway tab

In Sales > Orders open an order paid with Helcim. At the bottom of the order page, next to History and Additional, the VibeFox Helcim Gateway tab shows the Transaction ID (and the pre-authorization ID after a capture) with a Test mode label for test payments, the Transaction type and capture state, the Invoice, the Card and approval code, Approved / order / refunded amounts, the capture button and the refund form, the refund history and the Helcim notes of the order. The tab is shown to users who have access to the extension; capture and refunds need the right to modify it (set in System > Users > User Groups).

Capture

For an uncaptured pre-authorization, click Capture payment in the tab (the button shows the amount) and confirm Capture the pre-authorized amount through Helcim? The current order total, minus refunds, is captured. It may be lower than the authorized amount, but not higher. The capture uses the token of the mode the order was paid in. After a successful capture the order gets Order Status After Payment. If the capture fails, the tab shows the reason and adds it to the notes.

Refunds

In the tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), and click Refund via Helcim. Confirm Refund this amount through Helcim? This cannot be undone. Full and partial refunds of a purchase or a captured pre-authorization are supported, up to the amount Helcim actually charged, so after a partial approval you cannot refund more than the customer paid. For an uncaptured pre-authorization the button is Release pre-authorization: only the full amount can be released, the hold is removed and the order gets Canceled Status.

The refund is sent in the mode the order was paid in, so that mode's token must be set. It counts only when Helcim approves it. If Helcim declines it, the tab shows the error and no refund is recorded. A successful refund is added to the refund history and the notes with the Helcim refund transaction ID. A full refund sets the order to Refunded Status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status. A retry after a timeout does not refund twice.

Product returns in Sales > Returns do not send money back through Helcim. The extension does not receive Helcim webhooks: captures, refunds and voids made in the Helcim dashboard are not reflected in OpenCart, so make them from the order page.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Helcim Gateway is the first block on Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: opencart-payment-helcim and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Helcim is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already made are kept, and captures and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension always removes the license key and license status.

Troubleshooting

Helcim does not appear at checkout: check that the license is active, Enable / Disable is on, the current mode has its API token (Live API token, or Test API token in test mode) and the checkout currency is one of the Account currencies. The settings page shows a warning when the token is missing or the store currency is not allowed. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The customer saw We could not confirm your payment: Helcim did not answer, so the card may have been charged. The order note and the log name the Helcim invoice. Check that invoice in Helcim before charging the customer again. A retry within 5 minutes returns the original result and does not charge twice.

Customers see This payment method is temporarily unavailable: the API token was rejected by Helcim. The order note says to check the token and its permissions. Make sure the API access has transaction processing rights.

Customers see This payment method is not available. Please reload the checkout page.: the checkout session no longer matches the order, the payment method was turned off meanwhile, or the token or currency no longer fits. The customer reloads the checkout.

Payment failed with a Helcim reason: Helcim rejected the request, for example because of the card or the billing details. The order note and the log have the details.

The customer saw Your payment was received, but the order could not be completed: Helcim approved the payment, but OpenCart could not set the order status. The log has the reason. When the customer submits the same cart again, the status is set from the approved payment without a second charge.

Order is in the review status: read the notes in the VibeFox Helcim Gateway tab. Helcim's answer did not match the order (response verification failed). Check the transaction in Helcim, then fulfil the order or refund the payment.

Capture is not possible: the amount to capture must be greater than 0 and not above the authorized amount, and the token of the mode the order was paid in must be set.

Refund fails: read the message. An uncaptured pre-authorization can only be released in full. A message about the mode means the token of the mode the order was paid in is empty. A declined refund is not recorded. You do not have permission to capture or refund (modify this extension). means your user group has no right to modify the extension.

Test payments: test mode sends payments, captures and refunds to your Helcim test account. Orders keep the mode they were paid in, so switching the mode later does not move their captures and refunds to the other account.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Helcim Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable / Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. On OpenCart 4 the OpenCart event of the extension, which shows the message above the checkout page, is removed too. If Delete data on uninstall is on, the other gateway settings (title, description, API tokens, test mode, transaction type, account currencies, debug log switch) and the log are removed. If it is off, they are kept for a later re-install. The Helcim transactions and refunds are always kept, so orders paid before can still be captured and refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Helcim Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

Helcim is a trademark of its respective owner. This extension is not affiliated with or endorsed by Helcim.