README

Heartland PHP SDK

此 SDK 可以轻松地将您的 PHP 应用程序与 Heartland 的 Portico 网关 API 以及其他 API（如 MasterPass）集成。此外，此 SDK 还简化了与 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，并提供两种支付字段托管选项

• 自托管字段 - 此方法依赖于集成商提供的网页上的标准、命名恰当的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会为您处理并从您的服务器返回一个令牌以启动交易。

同样，如果您使用E3（适用于刷卡和按键输入方法）实施Heartland Secure，那么您的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. 创建新的拉取请求

包含的测试套件

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

在本地克隆此存储库，使用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