Magento 2 给 checkout 添加自定义支付方式

9.24K 浏览翻译

Magento 2 给 checkout 添加自定义支付方式

https://devdocs.magento.com/guides/v2.3/howdoi/checkout/checkout_payment.html

已知的,Magento checkout 包括两步:
  • Shipping Inoformation (配送信息)
  • Review and Payment Information (复核和支付信息)
可用的支付方式的列表将在复核和支付信息那步被渲染,而本文就描述了如何给这个列表添加自定义支付方式。
为了实现在结账中渲染一个支付方式,你需要执行以下几步:
  1. 新建执行(支付方式渲染的)组件的 JS 文件。
  2. 新建注册(支付方式渲染的)组件的 JS 文件。
  3. 新建这个支付方式的 template 。
  4. 在 checkout 的页面布局中生命这个新的支付方式。
第一步: 新建组件 .js 文件
你的支付方式必须被当作一个 UI 组件被渲染。为了兼容性、可升级性和易维护性,不要编辑Magento 源码,而要将你的定制内容添加到一个独立的模块中。为了让你的自定义 checkout 可以正确运行,你自定义 模块必须依赖于 Magento_Checkout 这个模块。模块的依赖关系必须在模块的 composer.json 中指定。
不要用 Ui 作为你的自定义模块名字,因为在指定路径时需要的 %Vendor%_Ui 这个标识可能会导致问题。
在你自定义的模块目录下创建组件(支付方式渲染) .js 文件。他必须在 <你的模块目录>/view/frontend/we/js/view 这个目录下。举例,在 Magento 模块中,支付方式渲染器放在 <Magento 模块目录>/view/frontend/we/js/viewpayment/method-renderer/ 这个目录下。
原本的支付方式的组件执行在
<Magento_Checkout 模块>/view/frontend/we/js/view/payment/default.js 这个文件中。通常,你的组件将会扩展这个组件。下面这个表格是原本组件方法的列表。
方法
                   
描述
                   
getCode():string
                   
返回支付方式的 code
                   
getData():object
                   
返回一个带有支付数据的 object,在选择支付方式或者扩展(比如点击继续按钮)时,这个 object 被发送到服务端。根据 MagentoQuoteApiDataPaymentInterface 得知,这个 object 必须包含数据。除了支付 code 和购买订单号外的所有的支付信息都包含在 additional_data 字段内。
                   
placeOrder():bool
                   
如果所有的验证都通过了,就会下单
                   
selectPaymentMethod():bool
                   
用户给  Quote JS 对象添加选中的支付方式的数据
                   
isChecked():string
                   
Returns the code of the selected payment method.
                   
isRadioButtonVisible():bool
                   
如果支付方式可用,则返回 true
                   
getTitle():string
                   
返回支付方式的 title.
                   
validate():bool
                   
用在 placeOrder() 方法中. 所以,你可以在你的模块中重写validate(),并且这个验证会在 placeOrder() 中执行。
                   
getBillingAddressFormName():string
                   
获取唯一的账单地址的 name
                   
disposeSubscriptions()
                   
结束对象的订阅。
                   
通常,支付方式渲染器是下面这个格式:
define(
    [
        'Magento_Checkout/js/view/payment/default'
    ],
    function (Component) {
        'use strict';
        return Component.extend({
            defaults: {
                template: '%path to template%'
            },
            // add required logic here
        });
    }
);
如果你的支付方式包含信用卡信息,你可以使用 Magneto 渲染器来实现一个信用卡表单:
<Magento_Payment 模块目录>/view/frontend/web/js/view/payment/cc-form.js。它也是扩展了原来的支付渲染器,但是有自己的方法,如下:
方法
                   
描述
                   
getData():object
                   
Returns an object with the payment data to be sent to the server on selecting a payment method and/or an extension (on pressing Continue button). It must contain data according to MagentoQuoteApiDataPaymentInterface. All the payment information except the method code and purchase order number is passed in the additional_data field. Adds credit card data (type, issue date, number, CVV).
                   
getCcAvailableTypes():array
                   
返回可用的信用卡的类型
                   
getIcons():bool
                   
返回可用信用卡类型的图片的链接.
                   
getCcMonths():object
                   
获取信用卡过期月份
                   
getCcYears():object
                   
获取信用卡过期年份
                   
hasVerification():bool
                   
一个标记,对于这个支付方式信用卡的 CVV 是否是必填的。
                   
hasSsCardType():bool
                   
Returns true if the Solo and Switch (Maestro) card types are available.
                   
getCvvImageUrl():string
                   
获取 CVV 提示图片的 URL.
                   
getCvvImageHtml():string
                   
获取 CVV 提示图片的 HTML.
                   
getSsStartYears():object
                   
Solo or Switch (Maestro) card start year.
                   
获取系统配置数据
你的支付方式可能需要获取这些数据,它们不能直接定义在布局(layout)配置、JS 组件或模板(template)中,比如,Magento 系统配置数据。这些配置存储在变量 window.checkoutConfig 中,它定义在 checkout 根模板中。
为了获取这些系统配置,你的支付方式或者一组支付方式必须调用 MagentoCheckoutModelConfigProviderInterface 这个接口,并且调用的 Class 必须通过 DI frontend 的配置注入到合成的 config provider 中. 下面的代码示例说明这些。
一个调用 MagentoCheckoutModelConfigProviderInterface 的 .php class 示例:
class MyCustomPaymentConfigProvider implements MagentoCheckoutModelConfigProviderInterface
{
...
    public function getConfig()
    {
        return [
            // 'key' => 'value' pairs of configuration
        ];
    }
...
}
一个自定义模块 <你的模块目录>/etc/fronted/di.xml 的 DI 配置文件:
...
<type name="MagentoCheckoutModelCompositeConfigProvider">
    <arguments>
        <argument name="configProviders" xsi:type="array">
            ...
            <item name="%Custom_provider_name%" xsi:type="object">MyCustomPaymentConfigProvider</item>
            ...
        </argument>
    </arguments>
...
</type>
添加其他的支付相关特色功能

你也可以在复核和支付支付信息的步骤中添加支付相关的特色功能(比如分享奖励和礼品登记等)。他们必须也是 UI 组件,并且可以在支付方式列表之前或者之后展示。这个在对应的 checkout 页面布局中配置。

第二步:创建注册渲染器的 .js 组件
在你的自定义模块目录下创建 .js UI 组件,它在渲染器列表中注册支付方式的渲染器。它必须放在
<你的模块目录>/view/fronted/web/js/view/ 目录下。比如,在 Magento 模块下,支付方式的渲染器放在 <Magento 模块目录>/view/fronted/web/js/view/payment/ 目录下。
这个文件的内容必须和下面的相似:
define(
    [
        'uiComponent',
        'Magento_Checkout/js/model/payment/renderer-list'
    ],
    function (
        Component,
        rendererList
    ) {
        'use strict';
        rendererList.push(
            {
                type: '%payment_method_code%',
                component: '%js_renderer_component%'
            },
            // other payment method renderers if required
        );
        /** Add view logic here if needed */
        return Component.extend({});
    }
);

如果你得模块添加几个支付方式,你可以在一个文件中注册所有的支付方式。

第三步:为这个支付方式组件创建模板(template)
在你得自定义模块目录下,创建一个新的 <你的模块目录>/view/frontend/web/template/<你的模板>.html 文件。这个模板可以用 Knockout JS 语法。你可以在任何支付方式的模块下找到一个示例 .html 模板。比如 Magento_Authorizenet 模块。

这个模板为了渲染 Authorize。在结账中的网络支付方式是 <Magento_Authorizenet 模块>/view/frontend/web/template/payment/authorizenet-directpost.html

第四步:在布局中生命这个支付方式
在你的自定模块下,创建一个 <你们模块目录>/view/frontend/layout/checkout_index_index.xml 新的文件。在这个文件中,添加以下内容:
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceBlock name="checkout.root">
            <arguments>
                <argument name="jsLayout" xsi:type="array">
                    <item name="components" xsi:type="array">
                        <item name="checkout" xsi:type="array">
                            <item name="children" xsi:type="array">
                                <item name="steps" xsi:type="array">
                                    <item name="children" xsi:type="array">
                                        <item name="billing-step" xsi:type="array">
                                            <item name="component" xsi:type="string">uiComponent</item>
                                            <item name="children" xsi:type="array">
                                                <item name="payment" xsi:type="array">
                                                    <item name="children" xsi:type="array">
                                                        <!-- Declare additional before payment components. START -->
                                                        <item name="beforeMethods" xsi:type="array">
                                                            <item name="component" xsi:type="string">uiComponent</item>
                                                            <item name="displayArea" xsi:type="string">beforeMethods</item>
                                                            <item name="children" xsi:type="array">
                                                                <item name="%your_feature_name%" xsi:type="array">
                                                                    <item name="component" xsi:type="string">%path/to/your/feature_js_component%</item>
                                                                </item>
                                                            </item>
                                                        </item>
                                                        <!-- Declare additional before payment components. END -->
                                                        <!-- Declare the payment method (the component that registrates in the list). START -->
                                                        <item name="renders" xsi:type="array">
                                                            <item name="children" xsi:type="array">
                                                                <item name="%group name of the payment methods%" xsi:type="array">
                                                                    <!-- Example of value: Magento_Authorizenet/js/view/payment/authorizenet-->
                                                                    <item name="component" xsi:type="string">%component_that_registers_payment_renderer%</item>
                                                                    <item name="methods" xsi:type="array">

                                                                        <!-- Add this if your payment method requires entering a billing address-->
                                                                        <item name="%payment_method_code%" xsi:type="array">
                                                                            <item name="isBillingAddressRequired" xsi:type="boolean">true</item>
                                                                        </item>
                                                                    </item>
                                                                </item>
                                                            </item>
                                                            <!-- Declare the payment method (the component that registrates in the list). END -->
                                                            <!-- Declare additional after payment components. START -->
                                                            <item name="afterMethods" xsi:type="array">
                                                                <item name="component" xsi:type="string">uiComponent</item>
                                                                <item name="displayArea" xsi:type="string">afterMethods</item>
                                                                <item name="children" xsi:type="array">
                                                                    <item name="%your_feature_name%" xsi:type="array">
                                                                        <item name="component" xsi:type="string">%path/to/your/feature_js_component%</item>
                                                                    </item>
                                                                </item>
                                                            </item>
                                                            <!-- Declare additional after payment components. END -->
                                                        </item>
                                                    </item>
                                                </item>
                                            </item>
                                        </item>
                                    </item>
                                </item>
                            </item>
                        </item>
                    </item>
                </argument>
            </arguments>
        </referenceBlock>
    </body>
</page>
针对在 checkout_index_index.xml 中如何声明一个新的支付方式的说明,请查看 app/code/Magento/Authorizenet/view/frontend/layout/checkout_index_index.xml
0