README

Heartland PHP SDK

此SDK使您的PHP应用程序与Heartland的Portico网关API以及其他API（如MasterPass）的集成变得简单，如Heartland Secure：超出范围设备，提供简单的半集成EMV接受，使全渠道开发人员能够实现真正的单点集成。

支持的功能包括

• 无卡支付（电子商务和移动支付）
• 有卡支付（零售和餐饮业）
• Secure Submit单次使用令牌化和多次使用令牌化
• Heartland Secure端到端加密（E3）
• 信用卡、礼品和忠诚度以及电子支票/ACH
• 周期性支付
• 直接与Heartland的超出范围设备（如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会为您处理，并返回一个令牌，以便从您的服务器发起收费。

同样，如果您实现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 '添加一些功能'）
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