Download the PHP package cardgate/magento2 without Composer

CardGate module for Magento 2

Support

This plugin supports Magento 2.1.x - 2.4.x.

Preparation

The usage of this module requires that you have obtained CardGate RESTful API credentials. Please visit My CardGate and retrieve your credentials, or contact your accountmanager.

Installation

The CardGate Module for Magento 2 is installed via Composer.

1. Go to Magento 2 root folder.

2. Enter following commands to install module:

   Wait while dependencies are updated.

3. Enter following commands to enable module:

4. If Magento is running in production mode, deploy static content:

Configuration

• Open the Magento Admin panel and view the CardGate plugin-configuration:
  • Stores > Configuration
  • Sales > CardGate
• Fill in the CardGate configuration section using the API credentials obtained earlier.
• Save config.
• Refresh the active payment methods:
  • CardGate information section
  • Payment methods > Refresh active payment methods
  • Check the output
• After the payment methods are refreshed successfully, all active Payment method sections can be enabled and edited.

Subscriptions (CuroPayments recurring)

This module can sell products as recurring subscriptions. The first order is paid normally by the customer; every following billing cycle is charged automatically through the CuroPayments recurring entry point, without customer interaction:

• test: https://secure-staging.curopayments.net/rest/v1/curo/recurring/
• live: https://secure.curopayments.net/rest/v1/curo/recurring/

See the CuroPayments documentation for the entry point details. The initial (authorizing) transaction of the order acts as the mandate for all following recurring charges.

1. Setup

1. Install/upgrade the module and run php bin/magento setup:upgrade (creates the cardgate_subscription table and the product attributes) followed by php bin/magento cache:flush.
2. Make sure the Magento cron is running (bin/magento cron:run from the system crontab). Subscription billing uses its own cron group cardgate (see etc/cron_groups.xml), so throttled settings of the default group do not delay billing.
3. Enable at least one of the allowed payment methods (see below).

2. Making a product a subscription

setup:upgrade adds three product attributes (group CardGate Subscription), available for every product type (simple, configurable, bundle, grouped and virtual):

Example: count 3 + unit month = billed every three months.

3. Cart and checkout rules

• One subscription product per cart. Adding a second subscription product is refused with the message "Only one subscription product is allowed per cart. You can add non-subscription products."
• Mixed carts are allowed. One-off products are billed only once by the initial order; only the subscription line-item is repeated.
• Allowed payment methods. A subscription is only created when the order is paid with: Bancontact (cardgate_bancontact / cardgate_mistercash), Creditcard, Direct Debit, iDEAL, Przelewy24 or onlineueberweisen. Orders paid with any other method are processed as normal orders without a subscription.

4. How a subscription is created

1. The customer places the order and pays the initial transaction at CardGate.
2. When the CardGate callback confirms the payment, the CardGate transaction id of the order is stored as the mandate and a subscription record is created for the subscription line-item (the sales_order_place_after observer tries too, but at that moment there is no mandate yet). Creation is idempotent: one subscription per order + product.
3. The subscription stores:
   • amount: row total incl. tax of the subscribed line-item;
   • shipping amount: the order shipping (incl. tax), scaled to the cycle length (cycle days / 30, limited between 0.25x and 2x);
   • currency, quantity, interval, payment method and mandate;
   • next billing date (next_run_at): order date + one interval, at 00:00 (UTC).

Renewal orders (created by a subscription) never create a new subscription.

5. Automated billing

The cron job cardgate_process_subscriptions runs every 5 minutes and picks up all active subscriptions whose next_run_at has passed. For each of them:

1. If skip next is set, the flag is cleared and the cycle is moved forward one interval without charging.
2. Otherwise a renewal order is created: a copy of the subscribed line-item of the originating order, with the same customer, addresses, shipping and payment method.
3. The renewal order is charged through the recurring entry point using the mandate, the order grand total and the order increment id as reference.
4. The regular CardGate callback then captures and invoices the renewal order just like a normal order.
5. On success cycles_billed is increased, last_order_id / last_transaction_id / last_run_at are stored, failures are reset and next_run_at moves one interval forward.

6. Failures and retries

After 5 consecutive failures the subscription is set to paused for review. Check last_error in the admin and var/log/exception.log / var/log/debug.log, fix the cause and resume the subscription.

7. Statuses

• active – billed automatically when due.
• paused – not billed. Resume resets the failures and schedules the next charge one interval from now.
• cancelled – final; never billed again and cannot be resumed or paused.

8. Customer self-service (My Account → My Subscriptions)

Logged-in customers can, for their own subscriptions:

• Pause / Resume;
• Skip the next billing cycle (active subscriptions only);
• Change the interval (shipping is rescaled and the next charge is scheduled one new interval from now);
• Cancel.

9. Administration (Sales → Operations → CardGate Subscriptions)

Requires the ACL resource Sales → CardGate Subscriptions (Cardgate_Payment::subscriptions); grant it under System → Permissions → User Roles for non-administrator roles.

The grid lists all subscriptions. On the edit page an administrator can change:

• shipping amount per cycle;
• the skip next flag;
• the next billing date;
• the interval count/unit;
• the status (active / paused / cancelled).

10. Troubleshooting

• Menu not visible: run setup:upgrade, cache:flush and log in again.
• Subscription not created: check that the product has Sell as Subscription = Yes, the payment method is allowed and the CardGate callback reached the shop.
• Nothing is billed: check that the cron runs and the cardgate group has entries in cron_schedule, and that the subscription is active with a past next_run_at.

Testing

The module ships with a PHPUnit test-suite that runs on PHP 7.4 up to 8.3.

phpunit.xml uses the PHPUnit 10/11 schema and tests/bootstrap.php registers a small PSR-4 autoloader so the standalone unit tests run without a full Magento installation. PHPUnit ^10.5 || ^11.0 is declared under require-dev, both of which support PHP 8.3.

Requirements

No further requirements.