README

此插件为 CardConnect 提供了 Craft Commerce 的集成。

需求

此插件需要 Craft CMS 3.1.0 和 Commerce 2.0.0 或更高版本。

安装

您可以从插件商店或使用 Composer 安装此插件。

从插件商店安装

前往项目控制面板中的插件商店，搜索 CardConnect for Craft Commerce。然后在弹出的模态窗口中点击安装按钮。

使用 Composer 安装

打开您的终端并转到 Craft 项目目录
```
cd /path/to/project
```

告诉 Composer 加载插件

composer require jmauzyk/commerce-cardconnect

在控制面板中，转到设置 → 插件，点击 CardConnect for Craft Commerce 的安装按钮；或告诉 Craft 安装插件
```
./craft install/plugin commerce-cardconnect
```

设置

CardConnect API 凭证

当您在 CardConnect 创建账户时，您将收到生产 API 凭证，包括用户名、密码、商户 ID 和端点。有关测试凭据和测试卡号，请参阅 CardConnect 支持中心。

添加 CardConnect 网关

转到 Commerce → 系统设置 → 网关，点击 新建网关 按钮。将网关类型设置为 CardConnect，填写您的测试或生产 API 凭证，然后保存。

支付表单

安装和配置网关后，表单字段将提交交易到 CardConnect。

默认支付表单

可以使用以下代码行输出基本 Commerce 支付表单。

{{ cart.gateway.getPaymentFormHtml({})|raw }}

从 v1.3.0 版本开始，使用 getPaymentFormHtml() 生成的支付表单将默认通过 CardConnect 的 Hosted iFrame Tokenizer 使用标记化的卡号。要更改标记化方法或恢复使用明文卡号，请在网关设置下选择相应的 标记化 配置。根据 CardConnect 的文档，强烈建议在将明文卡数据传递到请求之前对其进行标记化。

自定义支付表单

如果需要额外的定制，可以使用自定义支付表单，只要它们包括以下属性的输入

firstName
lastName
账户号码的格式为
- 明文卡片号码
- CardSecure令牌
有效期格式为
- 单独的月份和年份
- 组合到期日（MM/YYYY）
cvv

要使用自定义支付表单的iframe令牌化，请使用以下代码行输出托管iframe令牌化器，并附带隐藏的号码输入框。请确保包括您自己的JS事件处理程序，例如托管iframe令牌化器文档中所示的主要支付页面事件监听器。

{{ cart.gateway.getIframeNumberInput()|raw }}

要使用自定义支付表单的CardSecure API令牌化，请将以下代码作为基础。元素id和name属性必须按照所示进行设置，才能与令牌化javascript一起使用。

<!-- Card Number -->
    <input type="tel" id="cc-cardNumber" name="cardNumber" value="">
    <input type="hidden" id="cc-number" name="number" value="">


<!-- Expiry -->
    <select id="cc-month" name="month">
        <!-- options... -->
    </select>
    <select id="cc-year" name="year">
        <!-- options... -->
    </select>

    <!-- OR -->

    <input type="text" id="cc-expiry" name="expiry" value="">


<!-- CVV -->
    <input type="tel" id="cc-cvv" name="cvv" value="">


<!-- Tokenizer JS -->
    {% do view.registerAssetBundle("jmauzyk\\commerce\\cardconnect\\web\\assets\\cardsecurepaymentform\\CardSecurePaymentFormAsset") %}
    {% js %}initTokenizer('{{ gateway.getApiSubdomain() }}');{% endjs %}

为了加快令牌化性能，建议在调用令牌化之前使用类似的代码进行预连接或dns预取。

{% set subdomain = gateway.getApiSubdomain() %}
{% set apiUrl = 'https://' ~ subdomain ~ '.cardconnect.com' %}
{% do view.registerLinkTag({rel: 'preconnect', href: apiUrl}) %}
{% do view.registerLinkTag({rel: 'dns-prefetch', href: apiUrl}) %}

托管iframe令牌化器自定义

可以使用以下方式修改托管iframe的外观和功能：

srcParams —— 包含与iframe src URL一起传递的可选参数的数组
options —— 包含用于构建iframe标签的属性的数组

以下是如何自定义默认支付表单和令牌化数字输入的示例。所有CSS都将删除不必要的空白并进行正确编码，以便在iframe标签中使用。请参阅托管iframe令牌化器文档以获取可选参数和白名单CSS属性的完整参考。

{% set css %}
    body {
        margin: 0;
    }

    input {
        border: 1px solid #ccc;
        border-radius: 0;
        color: #333;
    }

    input:focus {
        border-color: #09c;
    }

    .error, .error:focus {
        border-color: #c00;
        color: #c00;
    }
{% endset %}
{% set srcParams = {
    tokenizewheninactive: craft.app.request.isMobileBrowser(true),
    formatinput: 'true',
    invalidinputevent: 'true',
    css: css
} %}
{% set options = {
    height: '42'
} %}

{# To output default payment form with customization... #}
{{ cart.gateway.getPaymentFormHtml({srcParams: srcParams, options: options})|raw }}

{# To output tokenized number input with customization... #}
{{ gateway.getIframeNumberInput(srcParams, options)|raw }}

自定义用户字段

CardPointe网关API支持在授权请求中支持自定义用户字段，这些字段可以在以后调用。这些自定义值可以使用UserFieldsEvent进行填充。

use jmauzyk\commerce\cardconnect\events\UserFieldsEvent;
use jmauzyk\commerce\cardconnect\gateways\Gateway;
use yii\base\Event;

Event::on(
    Gateway::class,
    Gateway::USER_FIELDS_EVENT,
    function (UserFieldsEvent $e) {
        $order = $e->order;

        $e->userFields = [
            'note' => $order->note ?? '',
            // ...
        ];
    }
);

jmauzyk / commerce-cardconnect

维护者

详情