Important Payment Module Changes in the Magento 2.2 Release

As you may notice from this blog there is a pretty high number of Magento 2 payment related articles. This article isn’t an exception. I’ve collected all changes introduced in the Magento\Payment module as part of the Magento 2.2.0 release.

Table of contents:

  • Comparison Method
  • Module Dependencies
  • API Signatures
  • The @api Annotation
  • JavaScript API
  • Deprecated Interfaces
  • Deprecated Methods
  • New Interfaces
  • Templates Changes
  • Unit Tests
  • Bug Fixes

Comparison Method

As for comparison, I decided to check out Magento 2.1.9 and Magento 2.2.0 with different Payment modules module-payment:100.1.7 vs module-payment:100.2.0 and go through line by line checking the changes.

Module Dependencies

The Magento\Payment module in the Magento 2.2.0 release no longer supports PHP 5.6 version. New PHP 7.1 version support has been introduced. Actually, this change affects all Magento 2.2 modules.

API Signatures

Magento team introduced better API coverage in the Magento 2.2 release. The Magento\Payment module is not an exception. Majority of the interfaces and classes from the Magento\Payment module are widely used for building custom payment integrations. These interfaces and classes were used without an official confirmation from Magento about its future. Now all these classes, interfaces and even JavaScript components are covered with the @api annotation.

The @api Annotation

This list of classes and interfaces were modified with @api annotation. It doesn’t mean all these PHP classes were added in the release. There were in the previous releases however, there was no @api annotation added.

  • Magento\Payment\Api\PaymentMethodListInterface
  • Magento\Payment\Api\Data\PaymentMethodInterface
  • Magento\Payment\Block\Form
  • Magento\Payment\Block\Info
  • Magento\Payment\Block\Adminhtml\Transparent\Form
  • Magento\Payment\Block\Form\Cc
  • Magento\Payment\Block\Form\Container
  • Magento\Payment\Block\Info\AbstractContainer
  • Magento\Payment\Block\Info\Cc
  • Magento\Payment\Block\Info\Instructions
  • Magento\Payment\Block\Transparent\Form
  • Magento\Payment\Block\Transparent\Iframe
  • Magento\Payment\Block\Transparent\Info
  • Magento\Payment\Gateway\Command\NullCommand
  • Magento\Payment\Gateway\Command\Result\ArrayResult
  • Magento\Payment\Gateway\Command\Result\BoolResult
  • Magento\Payment\Gateway\Config\ConfigValueHandler
  • Magento\Payment\Gateway\Config\ValueHandlerPool
  • Magento\Payment\Gateway\Data\PaymentDataObjectFactoryInterface
  • Magento\Payment\Gateway\Helper\ContextHelper (Shortcut for methods that can be used to verify payment context. Usage of this class should be avoided. The class was introduced for supporting backward compatibility.)
  • Magento\Payment\Gateway\Helper\SubjectReader (This class encapsulates implicit interfaces (array structures) used in payments implementation. The class was introduced for backward compatibility purpose with legacy implementation.)
  • Magento\Payment\Helper\Data
  • Magento\Payment\Model\Cart
  • Magento\Payment\Model\CcConfig
  • Magento\Payment\Model\CcGenericConfigProvider
  • Magento\Payment\Model\Config
  • Magento\Payment\Model\IframeConfigProvider
  • Magento\Payment\Model\Info
  • Magento\Payment\Model\MethodList
  • Magento\Payment\Model\Checks\CanUseCheckout
  • Magento\Payment\Model\Checks\CanUseForCountry
  • Magento\Payment\Model\Checks\CanUseForCurrency
  • Magento\Payment\Model\Checks\CanUseInternal
  • Magento\Payment\Model\Checks\Composite
  • Magento\Payment\Model\Checks\SpecificationFactory
  • Magento\Payment\Model\Checks\SpecificationInterface
  • Magento\Payment\Model\Checks\TotalMinMax
  • Magento\Payment\Model\Checks\ZeroTotal
  • Magento\Payment\Model\Checks\CanUseForCountry\CountryProvider
  • Magento\Payment\Model\Config\Source\Allspecificcountries
  • Magento\Payment\Model\Method\AbstractMethod (@deprecated 100.0.6), all methods deprecated since 2.1.0
  • Magento\Payment\Model\Method\Adapter (Use this class as a base for virtual types declaration) since 100.0.2
  • Magento\Payment\Model\Method\Free
  • Magento\Payment\Model\Method\Logger
  • Magento\Payment\Model\Method\SpecificationInterface
  • Magento\Payment\Model\Method\Specification\AbstractSpecification abstract class
  • Magento\Payment\Model\Method\Specification\Composite
  • Magento\Payment\Model\Source\Cctype (Inheritance of this class allowed as is a part of legacy implementation.)
  • Magento\Payment\Model\Source\Invoice (Inheritance of this class allowed as is a part of legacy implementation.)

JavaScript API

JavaScript files have @api annotation starting from Magento 2.2.0 version. It means custom payment modules can rely on the API when using or extending JavaScript files from the Magento\Payment module.

The following JavaScript Components are covered with the @api annotation (Magento\Payment\view directory):

  • credit-card-data.js
  • view/adminhtml/web/transparent.js – is not marked as API for some reason
  • credit-card-number-validator.js
  • cvv-validator.js
  • expiration-date-validator.js
  • validator.js
  • credit-card-type.js
  • cc-type.js
  • transparent.js
  • cc-form.js
  • view/payment/iframe.js
  • payments.js
  • free-method.js

Deprecated Interfaces

Only one interface has been deprecated. The Magento\Payment\Model\Method\ConfigInterface interface has no semantic meaning.

Deprecated Methods

The Magento\Payment\Helper\Data::getStoreMethods() has been used to get and sort available payment methods for a store specified. An alternative solution is to use the Magento\Payment\Api\PaymentMethodListInterface interface.

New Interfaces

Only one new interface has been introduced as part of the Magento 2.2.0 release. The Magento\Payment\Api\PaymentVerificationInterface is the payment provider codes verification interface. There is no default implementation of this interface because a code verification depends on payment method integration specifics. It is expected to implement the interface in a custom payment module.

Custom payment methods might implement this interface to provide specific mapping for payment methods, like AVS or CVV verification. The payment methods can map payment method info from internal sources, like an additional information, to specific international codes.

Unit Tests

All Unit Tests in the Magento\Payment module are based on the latest PHPUnit library 6.2.0. It means that Unit Tests for your custom payment modules should also be revisited as tests fail to execute with the Magento 2.2.0 installation.

As for the Magento\Payment module, I’ve noticed minor but important changes which helped to comply with the PHPUnit 6.2.0 version:

  • All the \PHPUnit_Framework_TestCase class usages have been refactored to the \PHPUnit\Framework\TestCase class.
  • The createMock() method is used instead of the getMock() method.
  • The createPartialMock() method is used instead of the getMock() method when only some methods should be mocked.
  • The expectException() method is used to set expected exception. Previously the setExpectedException() method was used.

Templates Changes

A short echo syntax <?= instead of long old-fashioned <?php echo syntax. Interesting to notice that the expiration year issue with value is still present in the frontend/templates/form/cc.phtml template.

Bug fixes

The validate-card-year validation rule was incorrectly checking year by using month validator. Now validate-card-year validates year correctly.

The Magento\Payment\Model\Method\Adapter::fetchTransactionInfo() method now returns a result of the method execution. My experience building and reviewing payment modules there aren’t many usages of the fetchTransactionInfo() method, but it is good that the method has been fixed.

There was also new Logger optional dependency and class variable introduced in the Magento\Payment\Model\Method\Adapter class. I am not sure why if there are no usages of the logger instance.

Before I finish

It is important to keep an eye on changes introduced between the major releases. Especially if it is an eCommerce payment functionality.

Drop me a line at or comment below with your thoughts on how you deal with updates and new Magento 2 versions.







Leave a Reply

Your email address will not be published. Required fields are marked *