Magento 2.1.3 Payment Changes Overview and Recommendations

Prev Next

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 the question about backward compatibility for custom payment integrations.

After reading this article you will know:

  1. What have new Payment API interfaces been introduced?
  2. How to add an 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 provide 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\PaymentMagento\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 assuming 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 getting a 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 provide 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 the 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

The new optional $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 the 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\Formclasses 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 the new block, you would want to create new Customer IP specification check you should declare it in di.xml file of a 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_USE_CHECKOUT.

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 the 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 the 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.

Posted on Dec 18, 2016

The Devletter

Subscribe to my Magento 2 tips and tutorials content.
Every week I send an interesting email directly to your inbox