VibeFox Cardcom for Adobe Commerce — Hilfe

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 extension, which the module uses to connect to Cardcom.

Internet access: your store must be reachable from the internet, so that Cardcom can send the payment notification.

Currency: the order currency must be ILS, USD, EUR or GBP. For any other currency the payment method is hidden at checkout.

Cardcom account: for live payments you need a Cardcom merchant account with a terminal number, an API username and an API password. Payments need only the terminal number and the API username. The API password is used only for refunds from Magento. Test mode works without a Cardcom account.

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-cardcom-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/CardcomPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_CardcomPayment 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 Cardcom. 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. Set Enable to Yes, leave Test mode at Yes, click Save Config and place a test order. For real payments set Test mode to No, enter the Live terminal number, Live API username and Live API password you received from Cardcom and click Save Config.

The module adds the Credit Card (Cardcom) 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 its own tables for the Cardcom payment attempts, their events and refunds. The notification URL is sent with every payment. Nothing has to be configured in Cardcom.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > Cardcom, 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. The license block and Remove data on uninstall are in the Default Config only. Save Config saves the whole page.

Some wrong values stop the save. Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a Cardcom title of 1 to 128 characters. Nothing was saved.), a Sort order that is not a whole number (Cardcom sort order must be a whole number. Nothing was saved.), and a Minimum order total or Maximum order total that is empty, negative or not a number (Cardcom amount limits must be non-negative. Nothing was saved.). Write amounts with a dot, for example 9.99. A Live terminal number with anything other than digits keeps its previous value, the other fields are saved, and Magento shows Cardcom: terminal number must contain digits only. Previous value was kept; other fields were saved.

After Save Config, while Enable is Yes, Magento shows a message for the scope you saved: Cardcom TEST mode: public terminal 1000; no real money. in test mode; Enter the Cardcom live terminal number and API username. The method is hidden until configured. when a live credential is missing; Cardcom live mode cannot use public test credentials. The method is hidden. when the live fields hold the public test terminal 1000 or the test user CardTest1994; Enter the API password to enable Cardcom online refunds. when the API password is empty in live mode; and Magento completes physical orders after native fulfilment. Cardcom payment alone does not create a shipment. when Success order status is Completed.

General

Enable: shows or hides Cardcom at checkout. In live mode it is shown only when the live terminal number and API username are set. Default: No.

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

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

Cardcom account

Test mode: uses the public Cardcom test terminal 1000 (API user CardTest1994). No real money is charged and no Cardcom account is needed. Default: Yes. Set it to No to accept real payments with the live credentials below. While it is on, customers see TEST — no real payments will be processed. under the payment method.

The terminal number, API username and API password are provided by Cardcom with your merchant account. These fields are used only in live mode.

Live terminal number: your Cardcom terminal number. Digits only.

Live API username: your Cardcom API username for this terminal. Spaces are removed on save.

Live API password: your Cardcom API password. It is needed only for refunds from Magento.

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

A payment is always checked and refunded with the mode and the Cardcom account it was made with: a test payment uses the test terminal even after you switched to live mode. If you change the live terminal number or API username, earlier live payments can no longer be checked or refunded from Magento until the original values are entered again.

Payment page

Operation: what Cardcom does on the payment page.

Maximum installments: the maximum number of installments (payments) the customer can choose on the Cardcom page, from 1 to 36. 1 means no installments. Values outside this range are changed to the nearest allowed value. Default: 1.

Success order status: what happens to the order after a confirmed payment. In every case Magento creates a paid invoice.

Payments that do not match the order always put the order On Hold, without an invoice.

Notification URL: shows, for reference, the address Cardcom sends payment notifications to. It looks like https://your-store/wcpcardcompaymentgateway/checkout/notify/. Each payment sends this address of the store view where the order was placed, with the order ID, automatically. Notifications are only pointers: the payment is always verified with Cardcom through your account.

Payment restrictions

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

Minimum order total: offer Cardcom only from this order total, in the base currency of your store. 0 means no minimum. Default: 0.

Maximum order total: offer Cardcom only up to this order total, in the base currency. 0 means no maximum. Default: 0.

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

Payment from specific countries: offer Cardcom only for billing addresses in these countries.

Advanced

Debug log: logs API requests and notifications to var/log/cardcom_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always logged. Credentials, card tokens, raw Cardcom answers, e-mail addresses and phone numbers are never written. When the file grows over 5 MB, it is kept as one older copy and a new file is started. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the settings in all scopes and the log (see Uninstall). The Cardcom payment history is always kept. Default: No.

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

Checkout

At the payment step the customer chooses the payment method (by default Credit Card (Cardcom)) and sees the description and the note You will be redirected to Cardcom to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module creates a Cardcom payment page for the order total in the order currency and sends the customer there. The page opens in Hebrew when the locale of the store view is Hebrew, otherwise in English. The product names of the order are passed to Cardcom. The customer enters the card details and, if installments are allowed, chooses the number of payments.

Before a new payment page is opened, earlier payment pages of the same cart are checked with Cardcom, so that a cart is not paid twice. If an earlier payment cannot be verified or is already paid, no new page is opened and the customer is asked to contact the store.

The order is marked paid only after Cardcom confirms it. Cardcom calls the notification URL, and the module takes from that call only the payment page code. It checks that this code was issued by your store for that order and then asks Cardcom server-to-server for the real result, with the terminal and API username the payment page was created with. The cart, the terminal, the amount and the currency must match. If the notification is late, the same check runs when the customer comes back. The results are handled even when Enable is No or the license is not active.

After a confirmed payment Magento creates the paid invoice with the Cardcom deal number as the transaction ID, the order moves to the status set in Success order status and the order e-mail is sent. The customer sees the standard order success page. A customer who comes back in another browser lands on the home page with Your Cardcom payment has been confirmed. If Cardcom has not confirmed the payment yet, the customer sees a Cardcom payment confirmation page with Your payment is being confirmed by Cardcom. There is no need to pay again. and a Check again link; the notification confirms the order as soon as it arrives. If the order is on hold or needs review, the page says Your Cardcom payment was received and needs manual review. Contact the store; do not pay again.

If the payment is not completed or Cardcom declines it, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart with Your Cardcom payment was not completed. You can try again or choose another method. If Cardcom refuses to open the payment page, the order is cancelled, the cart is restored and the customer sees Cardcom could not start the payment. Try again or choose another method. If the answer of Cardcom is uncertain, for example because of a connection problem, the order stays in Pending Payment and the customer sees Cardcom could not start or an earlier payment is uncertain. Contact the store before paying again.

Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). Cardcom has no cancellation API, so a payment page that is still open cannot be closed. If Cardcom later reports a payment for a cancelled order, the order is not reopened: a note asks you to review the payment, and you can refund it from the order page (see Orders and refunds).

The module works with the standard Magento checkout. It takes card payments on the Cardcom page only. It has no saved cards or one-click payments, no subscriptions, does not charge stored tokens, has no Cardcom invoice or receipt settings, no Bit, Apple Pay, Google Pay or PayPal via Cardcom, no iframe mode and no capture-later deals. Cardcom is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Cardcom, but Cardcom has not confirmed the payment yet. There is no invoice.

Processing: Cardcom confirmed the payment. The paid invoice carries the Cardcom deal number as the transaction ID. A note shows the deal, the amount received and the payment page code. Magento moves the order to Complete through its normal fulfilment.

On Hold: either Success order status is On hold after payment (the order has its invoice), or Cardcom confirmed a payment that does not match the order, for example a different sum or currency was charged. In the second case no invoice is created, and the note says payment needs review; no native invoice fabricated. with the reason. Compare the payment in the Cardcom dashboard with the order, then fulfil it or refund the payment.

Canceled: the payment was declined or not completed, Cardcom refused to open the payment page, or the order was cancelled in Magento.

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

A paid order is never changed by a later result. If a second successful payment arrives for a cart that is already paid (for example the customer paid in two browser tabs), or a payment arrives after the order was cancelled, nothing is invoiced. A note asks you to check and refund the extra payment. The notes are order comments that the customer does not see.

Cardcom payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, when known, Cardcom Low Profile code, Environment (test or live) and Funding transaction. The customer sees only the payment method title.

The Information tab of the order also has a Cardcom payment history section for Admin users who may view orders. Each payment attempt shows its status, Low Profile code, Funding transaction, Order currency, Captured currency, Card last four digits, Cardcom invoice number, Installments, Review, Captured amount, the Saved Cardcom token (with Charge and save token) and the refunds made through the module.

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 Cardcom. Full and partial refunds are supported, and several partial refunds can be made for one order. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Cardcom.

The refund is made in the order currency, up to the amount Cardcom actually captured minus the amounts already refunded. Before the refund the module checks the original payment with Cardcom again. The refund is sent with the mode and the Cardcom account the payment was made with, so the API username and API password of that account must be set. If Cardcom does not accept the refund, Magento shows the error and the credit memo is not created. After a successful refund Magento records it on the order with the Cardcom refund transaction in the transaction ID. A full refund closes the order.

Cardcom has no API to look up a refund. If the result of a refund is uncertain, for example because the connection was lost, the module blocks further refunds of that payment. Check the refund in the Cardcom dashboard. If it was made, open the Cardcom payment history of the order, tick I verified this exact completed refund in Cardcom., enter the Refund transaction number and click Reconcile refund. The note records it as confirmed by you. If Cardcom made a refund but Magento could not save the credit memo, the same Reconcile refund button creates the credit memo without sending a second refund.

Payments held for review, second payments and payments after a cancelled order have no invoice. To refund them, enter the amount in Refund captured amount in the Cardcom payment history and click Refund review payment. The money is refunded in the currency Cardcom captured, and a note records it; no invoice or credit memo is created. When such a payment is fully refunded, the hold is released, and an order without any paid invoice is cancelled.

The refund forms need the Admin right to create credit memos. Refunds made in the Cardcom dashboard are not reported back to the store. Record them with a credit memo and Refund Offline.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — Cardcom is the first row of the Cardcom group in Stores > Configuration > Sales > Payment Methods (Default Config), 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-cardcom 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, Cardcom is not shown to customers at checkout. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees Cardcom could not start the payment. Try again or choose another method. 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: payments already started are still confirmed, and refunds 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

Cardcom does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the order currency is ILS, USD, EUR or GBP. In live mode check that Live terminal number and Live API username are filled in with your own credentials, not the test terminal 1000 / CardTest1994. Check Payment from applicable countries and Payment from specific countries against the customer's billing address, and Minimum order total and Maximum order total. An order total of zero is not paid through Cardcom.

The payment went through, but the order stays Pending Payment: no verified result reached your store. Cardcom could not reach your store (for example because of a firewall, password protection or a local development site), or the check with Cardcom failed. The order is also confirmed when the customer returns to the store. Check that the terminal number and API username of the mode the payment was made in are still the ones it was made with. Turn on Debug log and look at the Log field.

The notification answers Missing or invalid lowprofilecode or Unknown lowprofilecode for this order: the call did not carry a payment page code issued by your store for that order. Nothing is changed.

The notification answers Indicator binding mismatch: Cardcom reported a payment for another cart or another terminal. Nothing is changed. Check that Live terminal number is the terminal of your account.

The notification answers Busy or indicator unavailable, retry: the cart was being confirmed by another request at the same moment, the credentials of the payment's mode are missing or changed, or Cardcom could not be reached for the check. Nothing is changed; the payment is checked again with the next notification or when the customer returns. Order not found means the order of the payment no longer exists.

Results fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification and return URLs too. The order is confirmed by the next notification or return that reaches the store.

The customer sees Cardcom could not start or an earlier payment is uncertain: Cardcom did not answer clearly when the payment page was requested, or an earlier payment page of the same cart cannot be verified. Check the Cardcom dashboard before the customer pays again. Turn on Debug log to see the reason.

The customer is back in the cart with Cardcom could not start the payment: Cardcom refused to open the payment page, the order currency is not supported, the live credentials are missing, the module was disabled or the license is not active. The order of that attempt is cancelled.

A payment was made but the order is On Hold or Canceled: the paid amount or currency did not match the order, a second payment arrived for a paid cart, or the payment arrived after the order had been cancelled, for example by the Pending Payment Order Lifetime cron. Read the order notes and the Cardcom payment history, then fulfil the order or refund the payment.

Refund fails with The original Cardcom API password is required for refunds.: enter the Live API password and try again.

Refund fails with The original Cardcom payment could not be verified. No refund was sent.: Cardcom could not be reached, or the terminal number or API username of the payment's mode was changed. Enter the original values and try again.

Refund fails with Cardcom refused the refund or its result is uncertain: check the Cardcom dashboard before you try again, because the refund may or may not have been made. If it was made, use Reconcile refund in the Cardcom payment history.

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 (for example On Hold after a mismatch) is refunded with Refund review payment in the Cardcom payment history.

For developers: the Magento event cardcom_p_supported_currencies extends the list of currencies (add only currencies enabled on your Cardcom terminal), and cardcom_p_low_profile_params changes the parameters of the payment page. The amount, currency, return and notification addresses cannot be changed.

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_CardcomPayment. It removes the data and the code.

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

The license key and license status are always removed. If Remove data on uninstall is Yes, the settings in all scopes and the log are removed too; after a re-install, enter the original Cardcom credentials again before you check or refund old live payments. If it is No, the settings are kept for a re-install. The Cardcom payment attempts, events and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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