Heartland iOS SDK

此 SDK 可简化您的 iOS 应用程序与 Heartland 的 Portico 网关 API 的集成。支持以下功能：

• 非接触式卡片（电子商务和移动应用）
• 接触式卡片（零售和餐饮业）
• Secure Submit 单次使用令牌化和多次使用令牌化
• Heartland Secure 端到端加密（E3）
• 信用，礼品卡和忠诚度以及 eCheck/ACH
• 周期性支付

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

开发者支持

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

需求

添加此pod还包括XMLDictionary，以及作为依赖项的Masonry CocoaPod。

安装

Heartland-iOS-SDK可通过CocoaPods获取。要安装，只需将以下行添加到您的Podfile，并运行"pod update"。

pod 'Heartland-iOS-SDK'

仅限iOS 9：白名单heartlandportico.com

如果您使用iOS SDK 9.0或更高版本编译应用程序，将受到App Transport Security的影响。当前，您需要在应用程序的plist中添加以下内容，以便白名单heartlandportico.com。

<key>NSAppTransportSecurity</key>
<dict>
<key>NSExceptionDomains</key>
    <dict>
        <key>heartlandportico.com</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSTemporaryExceptionMinimumTLSVersion</key>
            <string>1.2</string>
            <key>NSTemporaryExceptionRequiresForwardSecrecy</key>
            <false/>
        </dict>
    </dict>
</dict>

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更多地关注欺诈预防，但关于数据安全，EMV或芯片卡技术保证了支付卡的 authenticity，因此对于零售商来说是一个重要的关注点。

根据您或您的客户接受的支付环境，您可能需要支持这项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。

文档和示例

使用Swift

在pod文件中，请确保顶部区域使用use_frameworks!

platform :ios, '8.0'
use_frameworks!
pod ‘Heartland-iOS-SDK’

Swift令牌服务

以下是将敏感卡信息转换为单次使用令牌的所有示例。请求是异步的，因此您可以在UI线程上安全地运行此代码。

import Heartland_iOS_SDK

let tokenService: HpsTokenService = HpsTokenService(publicKey:"skapi_cert_Mc-xxxxxxxxxxxxxxxxxxxxxx");

tokenService.getTokenWithCardNumber("XXXXXXXXXXXXX",
                               cvc: "123",
                               expMonth: "12",
                               expYear: "2016") { (tokenData) in


    //use token
    tokenData.tokenValue
    //Call method after execution to continue.

}

Objective-C 令牌服务

以下是将敏感卡信息转换为单次使用令牌的所有示例。请求是异步的，因此您可以在UI线程上安全地运行此代码。

HpsTokenService *service = [[HpsTokenService alloc] initWithPublicKey:@"YOUR PUBLIC KEY GOES HERE"];

[service getTokenWithCardNumber:@"XXXXXXXXXXXXX"
                            cvc:@"012"
                       expMonth:@"3"
                        expYear:@"2017"
               andResponseBlock:^(HpsTokenData *tokenResponse) {

                   if([tokenResponse.type isEqualToString:@"error"]) {
                        self.tokenCodeResultLabel.text = tokenResponse.code;
                        self.tokenResultLabel.text = tokenResponse.message;
                   }
                   else {
                        self.tokenResultLabel.text = tokenResponse.tokenValue;
                   }

               }];

提示：包含的测试套件可以是使用SDK的代码示例的优秀来源！

测试与认证

测试卡数据

以下是我们的认证环境使用的卡号，以验证您的测试是否已成功。请注意，虽然某些变体（如4111111111111111）可以用于一般测试，但以下列出的卡号对于完成认证是必需的。对于“卡面识别”测试，Heartland可以为您提供启用EMV的测试卡。

测试异常

在进行集成测试时，您可能需要测试特定的发行商响应，例如“卡片拒绝”。由于我们的沙箱环境实际上并没有接触到发行商，因此我们已设计特定的交易金额来触发发行商响应代码和网关响应代码。请联系我们以获取可以用于模拟AVS、CVV和交易拒绝、错误以及其他可以在代码中捕获的响应的值的完整列表

 [service doTransaction:transaction
        withResponseBlock:^(HpsGatewayData *gatewayResponse, NSError *error) {

            //Token success or errors
            //gatewayResponse.tokenResponse.code

            //Gateway success or errors
            //gatewayResponse.responseCode

            //System or connection errors
            //error

        }];

贡献

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

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

包含的测试套件

包含的测试套件可以帮助确保您的贡献不会导致意外的错误，并且是引用实现案例的绝佳资源。您可以在此处找到测试

许可证

本项目的许可证为 GNU 通用公共许可证 v2.0。请参阅项目根目录下的 LICENSE.md 文件以获取更多详细信息。