Magento 2.1.3 Payment Changes Overview and Recommendations

Magento 2.1.3 Payment Changes Overview and Recommendations
In this article I will go through changes introduced in the Magento Payment module. I will answer question about backward compatibility for custom payment integrations.

New Magento 2.1.3 and Magento 2.0.11 releases include payment enhancements and improvements. Changes affect Paypal, Braintree and Authorize.Net payment modules in Magento Community Edition. In this article I review changes in the Magento\Payment module. Also, I will answer question about backward compatibility for custom payment integrations.

After reading this article you will know:

  1. What new Payment API interfaces have been introduced?
  2. How to add additional validator for payment method?
  3. What should you check in your custom payment method module to successfully upgrade to Magento 2.1.3?
  4. What deprecated methods you should not use?


Magento team has released new Magento 2.1.3 and Magento 2.0.11 versions which provides fixes and improvements for both Paypal and Braintree payment methods. Customers can store their credit cards using payment methods and reuse it for future purchases. All changes for both releases you can read at official Magento 2.1.3 Release Notes page.

I decided to have a closer look into Magento\Payment, Magento\Paypal and Magento\Braintree modules to have better understanding about new changes. I am interested in backward incompatible changes which may or may not affect custom payment implementations e.g. Realex Payments.

Payment Module Changes

First look into Magento\Payment\composer.json file allows to assume that there are no backward incompatible changes introduced as part the release. Minor Version of the module has changed to 100.1.3. This is a positive sign for custom payment modules.


There are 2 new API interfaces added. First one Magento\Payment\Api\PaymentMethodListInterface interface allows to get list of all payment methods and list of active payment methods.

namespace Magento\Payment\Api;

 * Payment method list interface.
interface PaymentMethodListInterface
     * Get list of payment methods.
     * @param int $storeId
     * @return \Magento\Payment\Api\Data\PaymentMethodInterface[]
    public function getList($storeId);

     * Get list of active payment methods.
     * @param int $storeId
     * @return \Magento\Payment\Api\Data\PaymentMethodInterface[]
    public function getActiveList($storeId);

Both methods return instance of Magento\Payment\Api\Data\PaymentMethodInterface interface. This data interface declares methods which provides information about payment method.

namespace Magento\Payment\Api\Data;

 * Payment method interface.
interface PaymentMethodInterface
    public function getCode();

    public function getTitle();

    public function getStoreId();

    public function getIsActive();

Both interfaces have its own implementations Magento\Payment\Model\PaymentMethod and Magento\Payment\Model\PaymentMethodList classes.

You can observe usage of these interfaces in the Magento\Payment\Block\Form\Container class.

Recommended to Read

Magento 2 Payment Gateway Configuration

Magento 2.0.6 Payment Changes

Magento 2 Payment Capture Request

Payment Form Container

In order to avoid breaking changes for the Magento\Payment\Block\Form\Container::__construct() method in minor releases Magento team uses deprecated private methods with static ObjectManager usage technique to introduce new class dependency. I believe that the ObjectManger object dependency will change in the next major release.

namespace Magento\Payment\Block\Form;

class Container
    private function getPaymentMethodList()
        if ($this->paymentMethodList === null) {
            $this->paymentMethodList = ObjectManager::getInstance()->get(
        return $this->paymentMethodList;
    // more code

New optonal $additionalChecks argument has been introduced in the Magento\Payment\Block\Form\Container::__construct(). This argument can be used to add custom validators for a payment method to be used on Checkout. There is no single example on how to add additional Magento\Payment\Model\Checks\SpecificationInterface class which represents a single specification check.

namespace Magento\Payment\Block\Form;

class Container extends \Magento\Framework\View\Element\Template
    public function __construct(
        \Magento\Framework\View\Element\Template\Context $context,
        \Magento\Payment\Helper\Data $paymentHelper,
        \Magento\Payment\Model\Checks\SpecificationFactory $methodSpecificationFactory,
        array $data = [],
        array $additionalChecks = []
    ) {
        $this->_paymentHelper = $paymentHelper;
        $this->methodSpecificationFactory = $methodSpecificationFactory;
        $this->additionalChecks = $additionalChecks;
        parent::__construct($context, $data);
    //more code

Both Magento\Multishipping\Block\Checkout\Billing and Magento\Sales\Block\Adminhtml\Order\Create\Billing\Method\Form classes extend Magento\Payment\Block\Form\Container class. Neither Billing nor Form class has an updated __construct() method to be able to have extra $additionalChecks argument. It means that for existing classes there is no way to use additional specification checks. This is not a big deal since Form class is used only for Order creation in Admin and Billing class is for Multishipping Checkout.

So for new block you would want to create new Customer IP specification check you should declare it in di.xml file of custom module:

    <type name="Pronko\Realex\Block\Adminhtml\Billing\Form">
            <argument name="additionalChecks" xsi:type="array">
                <item name="customer_ip_check" xsi:type="object">Pronko\Realex\Model\Check\CustomerIpCheck</item>

Additional specification check in MethodList

The Magento\Payment\Model\MethodList::getAvailableMethods() method has additional specification check called _CHECK_USECHECKOUT.

namespace Magento\Payment\Model;

class MethodList
    protected function _canUseMethod($method, \Magento\Quote\Api\Data\CartInterface $quote)
        return $this->methodSpecificationFactory->create(
    //more code

Make sure to check that can_use_checkout flag is set to "1" in config.xml configuration file for payment module. Without this flag method is not available on Magento 2 Checkout. Example as follows:


Deprecated getStoreMethods() Method

The Magento\Payment\Helper\Data::getStoreMethods() method is marked as deprecated. This is expected step since new API Magento\Payment\Model\PaymentMethodList interface has been introduced. Make sure to check your custom payment implementation and remove getStoreMethods() method usage to be ready for next major Magento release.

Frontend Changes

There is no backward incompatible changes in the Magento\Payment module on frontend side. The only change I've noticed is a change of Credit Card validator JavaScript components. Now credit card related JavaScript is located in Magento\Payment\view\base\ directory instead of Magento\Payment\view\frontend directory. This should not affect custom payment implementations since Magento automatically resolves location of a JavaScript component when a component is requested via define() function of RequireJS library.


Changes introduced in the Magento\Payment module are safe. There will be cases where custom payment integrations should be adjusted to have support of new Magento 2.1.3 release. For example can_checkout configuration setting set in a config.xml file may hide payment method on Checkout Payments page.

magento 2 payment

Related Articles


Next Article Previous Article

LinkedIn Twitter Facebook