VibeFox Helcim for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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

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

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Helcim Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure 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.

On install the module creates two order statuses, Helcim payment authorized and Helcim payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Helcim Gateway > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page warns you when the default currency of your shop is not one of the Account currencies, and, while the payment method is enabled, when the API token of the current mode is empty. In that case the payment method is hidden at checkout.

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 payment method description shown at checkout. Default: Pay securely with your credit card.

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.

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.

Clear saved tokens: tick a token and click Save to remove it. An empty field keeps the saved value.

Payment

Transaction type: how the card is charged.

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

Advanced

Debug log: writes API requests and responses to logs/wc_hlg_debug.log.php in the module folder. 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 module removes the gateway settings and its log files. The Helcim transactions, refunds and order statuses always stay, so orders paid before can still be captured and refunded after a re-install. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Credit card (Helcim), with a card icon) and enters Card Number, Expiry (MM/YY), CVC and Cardholder Name in the form under it. In test mode the form shows TEST MODE — payments go to a Helcim test account, no real charges are made. When the customer places the order, the module 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 on the checkout and nothing is sent to Helcim.

Your server then sends the card to Helcim as a purchase or a pre-authorization for the cart total in the cart currency. The billing address, phone and e-mail are sent for address verification. The payment shows in Helcim with an invoice number made of the cart number, -PS and a short code. Helcim answers in the same request. The order is created only after Helcim approves the transaction, and the customer lands on the standard order confirmation page. No order exists before that.

Only one payment attempt per cart runs at a time, and a cart that already has an order is never charged again. Every attempt uses an idempotency key. If Helcim does not answer, no order is created, 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 could not be created, the next attempt of the same cart creates the order without charging the card again.

Messages the customer may see on the checkout: 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 missing or 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 could not be created. The cart is kept. Technical details go to the log.

The module 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 order: the card was declined, Helcim did not answer, or the customer has not paid yet. Only the cart exists. Declines and errors are written to the log.

Payment accepted: a purchase was approved, or a pre-authorization was captured. The payment is recorded with the Helcim transaction ID, and a note shows the transaction ID, approval code, card type, last 4 digits and mode.

Helcim payment authorized: a pre-authorization was approved. The funds are only held. Capture them or release them with a full refund.

Helcim payment on hold: Helcim approved a transaction, but the amount, currency or transaction ID in its answer does not match the cart, for example after a partial approval or when the cart changed during the payment. The note says Helcim response verification FAILED. For a purchase, the payment is recorded with the amount Helcim actually charged. Check the transaction in Helcim before fulfilling.

Refunded: the payment was fully refunded through the module.

Canceled: an uncaptured pre-authorization was released. The customer was not charged.

If a second transaction is approved for a cart that already has an order, the order is not changed. A note asks you to check it and reverse or refund it in Helcim.

Helcim payment block

The order page shows a Helcim payment block with the transaction ID (and the pre-authorization ID after a capture), the transaction type and capture state, the invoice number, the card and approval code, the approved amount, the order total and the amount refunded, a Test mode badge for test payments, the refund history and the Helcim notes of the order. Capture and refunds need the right to edit orders.

Capture

For an order in Helcim payment authorized, click Capture payment in the block 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 becomes Payment accepted, and the payment is recorded with the capture transaction ID. If the capture fails, the block shows the reason and adds it to the notes.

Refunds

In the block enter the amount (the amount not refunded yet is filled in), optionally a reason, 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 becomes Canceled.

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 block 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. A partial refund does not change the status. A retry after a timeout does not refund twice.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Helcim. The module does not receive Helcim webhooks: captures, refunds and voids made in the Helcim dashboard are not reflected in PrestaShop, so make them from the order page.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Helcim Gateway is the first block on Modules > Module Manager > VibeFox Helcim Gateway > Configure, 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 shop. Below them are the line Product: presta-payment-helcim and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office 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 shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already made are kept, and captures and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module 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 cart currency is one of the Account currencies. The settings page shows a warning when the token is missing or the shop currency is not allowed. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The customer saw We could not confirm your payment: Helcim did not answer, so the card may have been charged. Look at the Log field: the error names the cart and 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 of the current mode is empty or was rejected by Helcim. The log says to check the token and its permissions. Make sure the API access has transaction processing rights.

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

The customer saw Your payment was received, but the order could not be completed: Helcim approved the payment, but PrestaShop could not create the order (for example, the module was disabled). The log has the reason. When the customer submits the same cart again, the order is created from the approved payment without a second charge.

Order is Helcim payment on hold: read the notes in the Helcim block. Helcim's answer did not match the cart (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.

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 Modules > Module Manager, open the menu next to VibeFox Helcim Gateway and choose Uninstall. The license key and license status of this module are always removed. If Delete data on uninstall is on, the gateway settings and the log are removed. If it is off, all settings are kept for a later re-install. The Helcim transactions and refunds and the order statuses Helcim payment authorized and Helcim payment on hold are always kept, so orders paid before can still be captured and refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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