VibeFox Helcim for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 7.0 or later, installed and active. Without WooCommerce the plugin refuses to activate.

PHP: 8.0 or later.

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 store 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 WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_helcim_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. 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.

4. Open the settings: WooCommerce > Settings > Payments > Helcim > Manage, or click Settings under the plugin name on the Plugins page.

5. Enter your VibeFox license key in the license block at the top of the page and click Activate.

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

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

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Helcim. Above the fields the page warns you when the store currency is not one of the Account currencies, and, while the gateway is enabled, when the API token of the current mode is empty. In both cases the gateway is hidden at checkout. In the list of payment methods the gateway is marked as needing setup until the current mode has a token.

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

Title: the payment method title shown at checkout. Default: Credit card (Helcim).

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: Use the Test API token (Helcim test account). Payments, captures and refunds go to your Helcim test account, and customers see a test mode notice. Refunds and captures 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.

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 gateway is hidden at checkout for other currencies.

Advanced

Debug log: Log API requests and responses to WooCommerce > Status > Logs, source wcp_helcim_gateway. Card numbers are reduced to the last 4 digits. CVC, expiry, tokens, names, addresses, e-mails and IP addresses are never logged. Default: off.

Delete data on uninstall: Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. Default: off.

Checkout

The customer chooses the payment method (by default Credit card (Helcim)) and enters Card Number, Expiry (MM/YY), CVC and Cardholder Name on your checkout. Icons for Visa, Mastercard, American Express and Discover are shown next to the title. In test mode the form shows TEST MODE — payments go to a Helcim test account, no real charges are made. Before sending, the plugin 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.

When the order is placed, your server sends the card to Helcim as a purchase or a pre-authorization for the order total in the order 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 order number and a short code. Helcim answers in the same request. The order is marked paid only after Helcim approves the transaction and the approved amount and currency match the order. Then the customer lands on the order received page.

Only one payment attempt per order runs at a time, and an order that is already paid is never charged again. Every attempt uses an idempotency key. If Helcim does not answer, the order stays Pending payment, and a retry within 5 minutes returns the original Helcim result instead of charging the card twice.

Messages the customer may see: 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. Technical details go to the order notes and the log.

The payment method works on the classic checkout, on the Checkout block (with the same card fields) and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin 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

Pending payment: the payment was declined or not confirmed yet. If Helcim did not answer, the order note asks you to check the Helcim invoice before charging the customer again.

Processing: a purchase was approved, or a pre-authorization was captured. Orders with only virtual downloadable products become Completed, the WooCommerce default. The order note shows the transaction ID, approval code, card type, last 4 digits and mode. The transaction ID is the Helcim transaction ID.

On hold (pre-authorization): the funds are only held. Capture them with the order action or release them with a full refund.

On hold after payment: Helcim approved a transaction, but the amount, currency or transaction ID in its answer does not match the order. The note says Helcim response verification FAILED. Check the transaction in Helcim before fulfilling.

Capture

Open the order (status On hold), choose the order action Capture Helcim pre-authorization and click Update. 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 Processing, and the transaction ID changes to the capture transaction. If the capture fails, the reason is shown and added to the order notes.

Refunds

Open the order, click Refund, enter the amount and click Refund via Credit card (Helcim) (the button shows your Title). Full and partial refunds of a purchase or a captured pre-authorization are supported. An uncaptured pre-authorization can only be refunded in full: the hold is released and the customer is not charged. 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, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the Helcim refund transaction ID. A retry after a timeout does not refund twice.

The plugin does not receive Helcim webhooks. Captures, refunds and voids made in the Helcim dashboard are not reflected in WooCommerce, so make them from WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Helcim. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site 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. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: captures and refunds still work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

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. On the Pay for order page the order currency counts. The settings page shows a warning in both cases.

Helcim did not answer and the order stays Pending payment: the card may have been charged. Read the order note and check the 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 order note 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 order note has the details.

Order is On hold after payment: read the order note. The order was pre-authorized and waits for capture, or Helcim's answer did not match the order (response verification failed).

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 refunded 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.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

For developers: the filter wc_hlg_supported_currencies changes the list of currencies, and wc_hlg_card_brands changes the card icons at checkout.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the plugin's own options and the logs are removed only if Delete data on uninstall was on. Otherwise they stay for a later re-install. Order data is part of the order history and is never deleted. Existing orders keep their payment notes and transaction IDs.

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