README

Heartland PHP SDK

此SDK简化了将PHP应用程序与Heartland的Portico网关API以及其他API（如MasterPass）集成，同时还简化了与Heartland Secure：Out-of-Scope设备的集成，提供简单的半集成EMV接受，为全渠道开发者提供真正的单点集成。

支持的功能包括

• 无卡支付（电子商务和移动支付）
• 有卡支付（零售和餐饮业）
• Secure Submit单次使用令牌化和多次使用令牌化
• Heartland Secure端到端加密（E3）
• 信用，礼品及忠诚度，以及电子支票/ACH
• 周期性支付
• 与Heartland的Out of Scope设备（如PaxS300）的直接通信

数据安全	API参考	测试与 认证	API密钥	链接
				注册账户 与Heartland合作

开发者支持

您并不孤单！在您开发过程中遇到任何问题时，请随时联系我们的团队寻求帮助！

安装

将此SDK添加到您的PHP项目中并使用一次。

<?php
require_once 'Hps.php';
?>

使用Composer？在您的composer.json中引入此库

{
    "require": {
        "hps/heartland-php": "*"
    }
}

然后运行composer update以拉取依赖并更新自动加载器。

API密钥

要开始创建测试交易，您需要获取一组公钥和私钥。这些可以在我们的开发者门户上创建账户时轻松获取。您的密钥位于您的个人资料信息下。

您在实现卡令牌化时将使用您的公钥，而在与我们的Portico网关通信时将使用您的私钥。更多详细信息请参阅我们的文档。

注意：创建账户时默认未启用多用途令牌化。您可以联系Heartland的专业产品团队以启用此功能。如果您想使用礼品和忠诚度、ACH和借记卡也是如此。

数据安全

• Secure Submit用于电子商务网站或移动应用程序（“非面对面”交易），利用一次性令牌化来防止卡数据通过商户或集成商的Web服务器。它只需要包含简单的JavaScript并提供两种支付字段托管选项

• 自托管字段 - 此方法依赖于集成商提供的Web页面上标准、名称适当的HTML表单控件。

• Heartland托管字段 - 此方法结合了Secure Submit服务和iframe来处理表单字段的呈现和收集敏感数据在Heartland服务器上。自PCI 3.1版本以来，PCI委员会和许多QSAs都提倡基于iframe的方法，因为这使得商户能够更容易地通过简化的SAQ A-EP表格实现PCI合规性。有关更多信息，请参阅CoalFire的白皮书。

• Heartland Secure用于面对面的零售商、酒店和其他“POS”应用程序，由三种不同的安全技术协同工作

• 端到端加密（E3）- 结合对称和非对称加密形成“基于身份的加密”方法，从刷卡的那一刻起就保持持卡人数据的加密。

• 令牌化 - 用非敏感的表示形式替换敏感数据值，这些表示形式可以存储用于定期收费、未来订单等。

• EMV - 虽然更多地关于欺诈预防，但EMV或芯片卡技术保证了支付卡的真实性，因此对于零售商来说是一个重要问题。

根据您的（或您的客户的）支付接受环境，您可能需要支持这些技术之一或多个，以及此SDK。此SDK还支持提交明文卡号的输入能力，但任何这样做的发展人员都将被期望证明符合PA-DSS。同样，任何计划代表其他商户处理明文卡数据的第三方集成商，在完成Heartland认证之前，将被期望证明其作为服务提供商的PCI DSS合规性。

如果您为您的Web或移动应用程序实现Secure Submit令牌化，您将永远不必处理卡号 - Heartland将为您处理并返回一个令牌，从您的服务器发起收费。

同样，如果您使用 Heartland Secure 与 E3（适用于刷卡和按键输入方式）进行实施，那么您的 POS 应用程序将超出 PA-DSS 范围。Heartland Secure 认证设备将始终返回 E3 加密数据，该数据可以安全地通过您的系统作为 SDK 输入。Heartland Secure 设备包括许多由 PAX 和 Ingenico 制造的流行型号。

总结一下，当您使用此 SDK 创建 paymentMethod 时，您有以下选项来安全地避免与敏感持卡人数据交互：

• 卡数据（磁条或 PAN）可以直接从网页浏览器发送到 Heartland，然后返回一个 SecureSubmit 单次使用令牌，该令牌随后发送到您的服务器。

• 加密的卡数据（磁条或 PAN）可以直接从 Heartland Secure 设备获取，然后传递到 SDK。

文档和示例

• eCheck
• 端到端
• 礼品
• iFrame 支付发票
• iFrame 定期注册
• 手动令牌化
• MasterPass
• 支付发票
• 销售点/E3 刷卡（仅磁条数据）
• 定期注册

快速提示：包含的 测试套件 可以是使用 SDK 的代码样本的绝佳来源！

流畅接口

请注意，我们的 SDK 提供了一个 流畅接口，允许您用如下所示的调用替换一个费用调用

$response = $chargeSvc->charge(17.01, "usd", TestCreditCard::validVisaCreditCard(), TestCardHolder::certCardHolderShortZip());

用如下所示的调用替换

$response = $this->service
                 ->charge()
                 ->withAmount(17.01)
                 ->withCurrency("usd")
                 ->withCard(TestCreditCard::validVisaCreditCard())
                 ->withCardHolder(TestCardHolder::certCardHolderShortZip())
                 ->execute();

在这两个示例之间，您在第二个示例中比在第一个示例中更容易阅读和理解代码正在做什么。这是一个很大的优势，有助于加速开发并减少在使用允许大量参数的方法时出现的错误。

快速提示：您将在包含的测试套件中找到 流畅 和 非流畅 示例。

测试和认证

快速提示：您可以通过审查包含的测试套件中的 认证测试 来提前开始认证。

测试卡数据

以下卡号由我们的认证环境使用，以验证您的测试是否成功。请注意，虽然像4111111111111111这样的变体可以用于一般测试，但以下列出的卡号是完成认证所必需的。对于卡面测试，Heartland可以为您提供启用EMV的测试卡。

测试异常

在您的集成过程中，您可能希望测试特定发行商的响应，例如“卡片拒绝”。由于我们的沙盒实际上并未向卡品牌发出授权请求，我们设计了特定的交易金额，可以触发发行商响应代码和网关响应代码。请联系 Heartland 获取可以收费以模拟AVS、CVV、交易拒绝、错误以及其他您可以在代码中捕获的响应的完整列表

     try
            {
                 $response = $this->service
                                  ->charge()
                                  ->withAmount(5)
                                  ->execute();
            }
            catch (HpsInvalidRequestException $e)
            {
                // handle errors for invalid arguments such as a charge amount less than zero dollars
            }
            catch (HpsAuthenticationException $e)
            {
                // handle errors related to your HpsServiceConfig (username, pw, api keys etc.)
            }
            catch (HpsCreditException $e)
            {
                // handle card-related exceptions: card declined, processing error, etc                 
            }

贡献

我们所有的代码都是开源的，我们鼓励同行开发者贡献并帮助改进它！

1. Fork它
2. 创建您的功能分支（git checkout -b my-new-feature）
3. 确保SDK测试通过
4. 提交您的更改（git commit -am 'Add some feature'）
5. 推送到分支（git push origin my-new-feature）
6. 创建新的Pull Request

包含的测试套件

包含的测试套件可以帮助确保您的贡献不会引起意外的错误，并且是您可以参考的出色的工作示例资源。

在本地克隆此存储库，使用Composer安装依赖项，然后运行PHPUnit对提供的测试进行测试。

$ git clone https://github.com/SecureSubmit/heartland-php.git
$ cd heartland-php
$ composer install
$ php vendor/bin/phpunit -c tests/phpunit.xml

这将默认运行所有测试套件。要运行单个测试套件，请将--testsuite选项传递给php vendor/bin/phpunit，并使用以下值之一

• fluent
• gateway-check
• gateway-credit
• gateway-debit
• gateway-giftcard
• gateway-token
• general
• certification

示例

$ php vendor/bin/phpunit -c tests/phpunit.xml --testsuite certification