VibeFox Helcim for Adobe Commerce — Помощь

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-helcim-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/HelcimPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_HelcimPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open Helcim. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, 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. Paste it into Live API token, and the token of your Helcim test account into Test API token if you have one. Choose the Transaction type and the Account currencies, set Enable to Yes and click Save Config. To test first, set Test mode to Yes and pay with your test account; then set it back to No.

The module adds the Credit card (Helcim) payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the Helcim payment attempts, the captures, refunds and releases, and the order notes it has written, and an internal secret for the idempotency keys, stored encrypted and never shown.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > Helcim, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Save Config saves the whole page. At the top of the group the module reminds you: Helcim Payment API: card details pass through this store to Helcim and are never saved. Production requires HTTPS and a PCI DSS compliant store (SAQ D). Test mode uses a separate Helcim account. No webhook is used; dashboard actions require accounting review.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Helcim: enter a title of at most 128 characters.); a Sort order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater.

When Enable is Yes, Magento shows warnings after Save Config: Helcim: the API token of the active mode is empty; the method is hidden., Helcim test mode is enabled. and Helcim: store currency is not in Account currencies.

General

Enable: shows or hides Helcim at checkout. It is shown only when the API token of the current mode is set and the cart currency is one of the Account currencies. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Credit card (Helcim). Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it at checkout. Default: Pay securely with your credit card.

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 token of a Helcim test account at the same API address. Payments, captures and refunds go to your Helcim test account, and customers see Helcim test mode is enabled. under the payment method. Captures, refunds and releases of an order always use the token of the mode the order was paid in. Default: No.

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

Magento stores the tokens encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved token, clear the field and click Save Config.

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.

Payment from Applicable Countries: All Allowed Countries offers Helcim for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Helcim only for billing addresses in these countries.

Minimum Order Total: offer Helcim only from this order total, in the base currency of your store. Default: 0 (no minimum).

Maximum Order Total: offer Helcim only up to this order total, in the base currency. 0 means no maximum.

Sort order: the position among the payment methods at checkout. A whole number, negative values allowed. Default: 0.

The countries and order totals are checked again when the card is sent. If the order no longer meets them, the customer sees Helcim order amount or country is no longer allowed.

Advanced

Debug log: writes API requests and responses to var/log/wc_hlg_debug.log.php in the Magento folder. The file cannot be opened from the web. API bodies, card details, tokens, e-mails and long numbers are never logged. Errors (declined or failed payments, API errors) are always logged, even when this is off. The file is emptied when it grows over 5 MB. Default: No.

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

Delete data on uninstall: when Yes, uninstalling the module with its data deletes the gateway settings, the internal secret and the log (see Uninstall). The license key is always removed. The payment and refund history always stays. Uninstall reads the value of the default store view, so set it in the Default Config. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Credit card (Helcim)), sees the description and enters Card number, Expiry (MM/YY), CVC and Cardholder name in the form under it, with the billing address. Empty fields give Enter the card number, expiry, CVC and cardholder name. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The card is then sent to your store in a separate request and is not saved with 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 such as Please enter a valid card number. 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 order total in the order currency. The billing address, phone, e-mail and the customer's IP address are sent for address verification. The payment shows in Helcim with an invoice number made of the order number, -MG and a short code. Helcim answers in the same request.

The order is marked paid only after Helcim approves it and the approved amount, currency and transaction ID match the order. For a purchase, Magento then creates the invoice with the Helcim transaction ID, the order becomes Processing and the order e-mail is sent. For a pre-authorization, the authorization is recorded, the order becomes Processing and is put On Hold, and the order e-mail is sent. The customer sees the standard order success page. After a pre-authorization it shows Helcim authorized your card. Funds have not been captured., after a mismatch Your Helcim payment needs review. Contact the store; do not pay again.

If the payment is not approved, the order stays in Pending Payment, the customer stays on the checkout with a message and can enter the card again and click Place Order. The same order is paid; no new order is created. Messages the customer may see: Your card was declined. Please check the card details or use another card. when Helcim declines; This payment method is temporarily unavailable. when the API token was rejected; We could not confirm your payment. Retry the same card shortly; contact the store before using another card. when Helcim does not answer; The previous Helcim result is unknown or its safe retry window expired. Contact the store; do not pay with another card. when the retry comes too late or with other data; Helcim: this cart is already paid, reserved or closed. Do not pay again. when the cart is already paid or another payment of the cart is in progress; Helcim is busy. Please retry. on a double submit; This payment method is unavailable for this currency or amount. when the method was disabled or the currency is not allowed.

Only one payment attempt per cart runs at a time, and a cart that is already paid is never charged again. Every attempt uses an idempotency key. If Helcim does not answer, a retry of the same card within 4 minutes returns the original Helcim result instead of charging the card twice. After that, the payment must be checked in Helcim and reconciled on the order page.

The page your-store/wcphelcimgateway/checkout/card shows the last unpaid Helcim order of the customer's session with the same card form and the button Cancel unpaid order / release authorization, which cancels the order (the stock goes back) and restores the cart. Unpaid orders left in Pending Payment are cancelled by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). When Helcim did not answer, the result is unknown and the cron leaves the order for the 4 minutes in which the customer can retry the same card. After that the cron marks the attempt failed and cancels the order with a note to check its Helcim invoice number in your Helcim account. Reconcile the attempt before then if Helcim approved it. If the cron cannot release a pre-authorization, or a payment needs review, it leaves the order unchanged and adds a note. Cancelling such an order in the Admin shows the error.

The module works with the standard Magento (Luma) checkout. It 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. Helcim is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed, but Helcim has not approved a payment yet: the card was declined, Helcim did not answer, or the customer has not entered the card. There is no invoice.

Processing: a purchase was approved, or a pre-authorization was captured. The invoice is created with the Helcim transaction ID as the transaction ID, and a note shows the approved amount.

On Hold after a pre-authorization: the funds are only held. There is no invoice. The note says Helcim funds authorized only; no captured funds or invoice. Use Capture authorized funds or Release authorization. After Unhold the order is Processing, and the cron does not cancel it.

On Hold after a mismatch: Helcim approved a transaction, but its amount, currency or transaction ID does not match the order, for example after a partial approval or when the order changed. The note says Helcim verification FAILED with the approved amount. No invoice is created. Check the transaction in Helcim, then fulfil the order or refund the actual funds (see Payment history).

Canceled: the unpaid order was cancelled, or an uncaptured pre-authorization was released. The customer was not charged.

Closed: the payment was fully refunded with a credit memo.

If a second payment is approved for a cart that is already paid by another order, the order of that payment is not marked paid. A note asks you to review the original account; send the duplicate back with Refund actual review funds (see Payment history). The notes are order comments that the customer does not see.

Helcim payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Helcim transaction ID, Environment (test or live), Card type and Last four digits. The customer sees only the payment method title.

Payment history

The Information tab of the order shows Helcim payment history: every payment attempt with the transaction ID and invoice number, the mode and transaction type, the requested and approved amount, the result and the card, and Helcim operation history with every capture, refund and release, its amount, result, Helcim transaction ID and the credit memo it belongs to.

Capture authorized funds: for a pre-authorized order, captures the full order total (minus refunds), up to the authorized amount, in the account the order was paid in. Magento creates the invoice with the capture transaction ID and the order becomes Processing. Needs the right to create invoices.

Release authorization: releases an uncaptured pre-authorization in full and cancels the order, without a credit memo. Needs the right to cancel orders. Cancelling an unpaid pre-authorized order in Magento (after Unhold) releases the authorization too.

Refund actual review funds: for a purchase on hold after a mismatch, or a duplicate payment of an already paid cart, sends back an amount you enter, up to what Helcim actually charged, without an invoice or credit memo. Needs the right to create credit memos.

Reconcile: Helcim has no webhook or transaction lookup, so when Helcim did not answer, the result of a payment, capture, refund or release stays unknown. Check the exact transaction in your Helcim account (amount, currency, the account of the original payment). Then tick I verified this exact APPROVED transaction, amount, currency and original Helcim account., enter the Verified numeric transaction ID and click Reconcile verified result without another API operation. The module records the result (invoice, capture, release or credit memo) without sending anything to Helcim again. Needs the rights to create invoices, cancel orders and create credit memos. Until an unknown operation is reconciled, no other operation of the order is possible.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Helcim. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Helcim.

The refund is made in the order currency, up to the amount Helcim actually charged minus the amounts already refunded. It is sent in the mode the order was paid in, so that mode's token must be set. If Helcim does not approve the refund, Magento shows the error and the credit memo is not created, for example Helcim did not approve the operation. No native financial document was committed. After a successful refund Magento records it with the Helcim refund transaction ID. A full refund closes the order. A retry after a timeout does not refund twice.

The module does not receive Helcim webhooks: captures, refunds and voids made in the Helcim dashboard are not reflected in Magento. Make them from the order page, or record them yourself (for example with Refund Offline) after checking your accounting.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — Helcim is the first row of the Helcim group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-helcim and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 card is sent anyway, nothing is sent to Helcim, the order stays in Pending Payment and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: captures, refunds, releases and reconciliation work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Helcim does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, that the current mode has its API token (Live API token, or Test API token in test mode) and that the cart currency is one of the Account currencies. Magento shows a warning after Save Config when the token is missing or the store currency is not allowed. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total.

The customer paid, but the order stays Pending Payment: Helcim did not answer, so the result is unknown and the card may have been charged. Open the order: Helcim payment history shows the attempt and its Helcim invoice number. Find that invoice in your Helcim account. If it was approved, reconcile it on the order page (see Payment history); the order is then invoiced without a second charge. Do it before the Pending Payment Order Lifetime ends. After that the cron cancels the order with a note, and an approved charge must be refunded in your Helcim account. A retry of the same card within 4 minutes also returns the original result.

Customers see This payment method is temporarily unavailable: Helcim rejected the API token of the current mode. Make sure the API access has transaction processing rights and the token is pasted into the field of the mode you use.

The customer saw Helcim payment could not be confirmed: an unexpected error occurred after the card was sent. Check the order and its Helcim payment history before the customer pays again, and turn on Debug log to see the reason.

The customer saw Helcim module secret is missing: the internal secret that the module creates at installation is missing from the settings. Re-install the module, as the message says.

Order is On Hold after payment: read the order notes. After a pre-authorization, capture or release the funds. After a mismatch, check the transaction in Helcim, then fulfil the order or use Refund actual review funds.

Capture is not possible: only the full order total minus refunds can be captured, and not more than the authorized amount. The token of the mode the order was paid in must be set.

Refund or capture fails with A Helcim operation is uncertain or under review: an earlier operation of the order has an unknown result or a mismatch. Reconcile it first (see Payment history).

Refund fails with The original Helcim account token is missing: the order was paid in test or live mode, and the token of that mode is not set. Enter it and try again.

The Helcim order changed. Reload the Credit Memo before requesting a refund: another refund or invoice of the order was saved while the credit memo was open. Open the credit memo again.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (pre-authorized or On Hold after a mismatch) cannot be refunded with a credit memo; release the authorization or use Refund actual review funds.

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 settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_HelcimPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_HelcimPayment to remove the data, then bin/magento module:disable Vibefox_HelcimPayment, delete the folder app/code/Vibefox/HelcimPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Delete data on uninstall is Yes, the gateway settings, the internal secret and the log are removed too; a re-install creates a new secret. If it is No, the settings are kept for a re-install. The Helcim payment, capture and refund history is always kept, so orders paid before can still be captured and refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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