SumUpSDK 6.0.0

SumUpSDK 6.0.0

×

由 SumUp 维护。

SumUpSDK 6.0.0

SumUp mPOS SDK - iOS

Platform Created Supports Version License CocoaPods Carthage compatible

此仓库提供了一个本机 iOS SDK，使您能够集成 SumUp 的专有卡终端和其支付平台，以接受信用卡和借记卡支付（包括 VISA、MasterCard、American Express 等）。SumUp 的 SDK 通过蓝牙（BLE 4.0）或音频线缆连接，透明地与卡终端通信。在启动结账时，SDK 通过适当的屏幕引导用户完成支付过程的每个步骤。作为过程的一部分，SumUp 还提供了卡终端设置屏幕以及持卡人签名验证屏幕。结账结果将带有关键数据返回以供您的记录。

永远不会将敏感的卡数据传递到或存储在商户的手机上。所有数据都通过卡终端加密，卡终端已完全符合最高行业标准（PCI、EMV I & II、Visa、MasterCard & Amex）。

有关更多信息，请参阅 SumUp API 文档。。

先决条件

  1. 通过 SumUp 的 国家网站 注册了商户账户（或收到了测试账户）。
  2. 收到了 SumUp 卡终端：Solo、Air、Air Lite、PIN+ 终端、芯片和签名读卡器或 SumUp Air Register。
  3. 通过 SumUp 开发者仪表板申请了联盟（访问）密钥。
  4. 部署目标 iOS 12.0 或更高版本。
  5. 建议使用 Xcode 13 和 iOS SDK 15 或更高版本进行开发。
  6. iPhone、iPad 或 iPod touch。

兼容性

  • 从固件版本1.0.1.84开始，序列号以108、109或更高开始的Air卡读卡器需要iOS SDK 4.3.0及更高版本。如果您需要支持这些读卡器，请更新到最新的iOS SDK版本。

小费

小费有三种模式

  1. 无小费。创建SMPCheckoutRequest对象时，将tipAmount设置为nil。

  2. 通过tipAmount属性进行编程式小费。在自己的UI中询问用户合适的小费金额，然后设置SMPCheckoutRequest上的tipAmount属性。这将被添加到总额中，但在结账期间将单独显示给用户。

  3. 在卡读卡器上小费。TCR在卡读卡器的显示上直接提示客户小费金额，而不是在iPhone或iPad显示上提示。

在卡读卡器上小费（TCR）

注意：并非所有读卡器都支持此功能。要确定最后使用的读卡器是否支持此功能，您应始终检查SMPSumUpSDK.isTipOnCardReaderAvailable。为了避免提示无小费，您必须自己处理这种情况。

为此

在调用SMPSumUpSDK checkoutWithRequest:fromViewController:completion:之前，请检查SMPSumUpSDK.isTipOnCardReaderAvailable。

  • 如果是NO，您应该自行提示用户输入小费金额，并在SMPCheckoutRequest上设置tipAmount。

  • 如果是YES，您可以在SMPCheckoutRequest上将tipOnCardReaderIfAvailable设置为YES。如果您这样做，不要提示用户输入小费金额或在小费上设置tipAmount。

目录

若要支持 SumUp Air Register，请阅读我们的附加参考资料Air Register 设置指南。

若要支持 SumUp Air Register，请阅读我们的附加参考资料 Air Register 设置指南。

手动集成

SumUp SDK 作为 XCFramework SumUpSDK.xcframework 提供，其中包含头文件和包含资源（如图像和本地化）的包。请按照以下步骤准备您的项目：

  1. 将 SumUpSDK.xcframework 拖到 Xcode 项目“通用”标签页中的“框架、库和嵌入式内容”。
  2. 确保存在所需的Info.plist 密钥。

注意：您可以使用与 SumUp SDK 一起提供的 示例应用 作为参考项目。Xcode 项目包含用 Objective-C 和 Swift 编写的示例应用。有关更多信息，请参阅测试您的集成。

通过CocoaPods集成

SumUp SDK可以通过CocoaPods进行集成。

target '<Your Target Name>' do
    pod 'SumUpSDK', '~> 4.0'
end

确保存在所需的Info.plist 密钥。

要了解更多关于为CocoaPods设置项目的信息，请参阅官方文档。

通过Carthage集成

⚠️由于最新版本的Carthage（0.35.0）尚未提供与XCFrameworks的分布式支持，该问题已作为一个开放问题（#2799）提出来解决。一旦问题得到修复，我们预计Carthage将能够恢复正常工作。

按照以下步骤使用Carthage将SumUp SDK集成到您的项目中

  1. 将以下行添加到您的Cartfile中

     github "sumup/sumup-ios-sdk"

  2. 运行carthage update sumup-ios-sdk

  3. 将Carthage/Build/iOS/SumUpSDK.xcframework拖放到Xcode项目“通用”选项卡中的“框架、库和嵌入内容”。

  4. 确保存在所需的Info.plist 密钥。

要了解更多关于为Carthage设置项目的信息，请参阅官方文档。

注意：有关更多信息，请参阅测试您的集成。

通过Swift PM集成

最新版本的Swift Package Manager已经支持将二进制框架作为Swift Packages分发。遗憾的是，存在一个错误（错误报告SR-13343），该错误将框架作为静态库添加，而不是作为嵌入的动态框架。请按照以下方法绕过此问题以通过Swift PM管理SumUp SDK版本

要求：Xcode 12 beta 6 (swift-tools-version:5.3)

  1. 将包依赖项添加到存储库https://github.com/sumup/sumup-ios-sdk（文件 > Swift Packages > 添加包依赖...），版本为Up to Next Major: 4.0.0
  2. 在集成弹出窗口中不选中SumUpSDK复选框（添加包到 ...:） Swift PM - do not auto-integrate SDK
  3. 从项目导航器中，将 SumUpSDK/Referenced Binaries/SumUpSDK.xcframework 拖放到您的 Xcode 项目的“通用”标签页中的“框架、库和嵌入内容”。
  4. 确保存在所需的Info.plist 密钥。

要了解更多关于添加 Swift 包依赖项的信息，请参阅官方文档。

测试您的集成

在您的调试设置中，您可以调用 +[SMPSumUpSDK testSDKIntegration]。它将运行各种检查并将结果打印到控制台。请不要在生产版本中调用它。

支持的设备方向

SDK 支持iPad上的所有设备方向，iPhone上的纵向方向。您可以根据需要支持iPhone上的其他方向，但请注意，SDK的UI将始终以纵向显示在iPhone上。请参阅示例应用程序的Info.plist或Xcode目标编辑器的“通用”标签中的UISupportedInterfaceOrientations。

隐私信息plist键

SumUp SDK 需要访问用户的地理位置和蓝牙外围设备。如果您的应用程序还没有请求用户权限，SumUp SDK 将在首次登录或结账尝试时请求。请在您的 info.plist 文件中添加以下键。

    NSLocationWhenInUseUsageDescription
    NSBluetoothAlwaysUsageDescription
    NSBluetoothPeripheralUsageDescription (unless your deployment target is at least iOS 13)

注意

  • 有关所需权限的更多信息，请参阅示例应用程序的 Info.plist。
  • 您可以通过提供本地化的 InfoPlist.strings 文件来提供本地化。
  • 如需更多信息，请参阅[iOS 开发者库](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW26)中关于iOS 8及以后的[位置使用](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW20)和[蓝牙外设使用](https://developer.apple.com/library/ios/documentation/General/Reference/InfoPlistKeyReference/Articles/CocoaKeys.html#//apple_ref/doc/uid/TP40009251-SW20)的文档。

开始使用

导入SDK

在Objective-C源文件中导入SDK，可以使用#import <SumUpSDK/SumUpSDK.h>。如果项目中启用了模块支持，可以使用@import SumUpSDK;代替。

在Swift中，使用import SumUpSDK。您不需要将任何头文件添加到桥接头中。

验证应用程序

在调用SumUp SDK的任何其他功能之前，您需要使用您的联盟（访问）键设置SDK。

[SMPSumUpSDK setupWithAPIKey:@"MyAPIKey"];

注意：setupWithAPIKey:会检查用户的地理位置权限。因此，请勿将此方法作为应用程序启动的一部分调用。此方法必须在主队列上调用。

登录

应用程序验证后，需要登录一个已注册的SumUp商户账户。从您的UIViewController显示登录界面，使用以下方法

[SMPSumUpSDK presentLoginFromViewController:vc
                                   animated:YES
                            completionBlock:nil];

注意：还可以使用令牌登录账户，而无需在SDK中输入用户的SumUp登录凭据。请参阅透明认证部分。

要注销SDK，请参阅logoutWithCompletionBlock:。

交易标识符

foreignTransactionID 标识符将与交易相关联，并可用于检索有关交易的详细信息。请参阅API 文档获取详细信息。请确保该 ID 在 SumUp 商户账户及子账户范围内是唯一的。其长度不能超过 128 个字符。

// set an optional identifier
[request setForeignTransactionID:@"my-unique-id"];
跳过成功屏幕

为了跳过交易成功的最后出现的屏幕，可以使用 SMPSkipScreenOptionSuccess 选项。设置此选项时，您的应用程序负责向客户显示交易结果。结合使用收据 API，您的应用程序还可以发送自己的收据，请参阅 API 文档 获取详细信息。请注意，当使用 SumUp Air Lite 读取器时，成功屏幕仍然会显示。

跳过失败屏幕

为了跳过交易失败的最后出现的屏幕，可以使用 SMPSkipScreenOptionFailed 选项。设置此选项时，您的应用程序负责向客户显示交易结果。请注意，当使用 SumUp Air Lite 读取器时，失败屏幕仍然会显示。

提前准备SumUp卡读卡器

为了准备SumUp卡读卡器以便结账，可以提前调用prepareForCheckout方法。需要登录已注册的SumUp商户账户，并且读卡器必须已经设置。您应该使用此方法让SDK知道用户很可能即将开始结账尝试；例如输入金额或添加商品到购物车时。这允许SDK采取适当的措施，如尝试唤醒已连接的读卡器。

透明身份验证

要无用户输入SumUp凭证的情况进行账户认证，可以使用OAuth2.0生成访问令牌，并用它来透明地登录SumUp SDK。

[SMPSumUpSDK loginWithToken:@"MY_ACCESS_TOKEN" 
                 completion:nil];

有关获取令牌的信息，请参阅API文档。

如果令牌无效，将返回SMPSumUpSDKErrorInvalidAccessToken。

启动结账请求

使用以下结账请求开始付款

[SMPSumUpSDK checkoutWithRequest:request
              fromViewController:vc
                      completion:^(SMPCheckoutResult *result, NSError *error) {
                      // handle completed and failed payments here
                      // retrieve information via result.additionalInfo
}];

结账错误代码

在 checkoutWithRequest: 完成块中接收到的 错误代码 的可能值。

更新结账偏好设置

登录后，您可以让商家检查和更新他们的结账偏好设置。商家可以选择他们首选的卡片终端并在需要时设置一个新的终端。商家可用的偏好设置取决于各自的账户设置。

[SMPSumUpSDK presentCheckoutPreferencesFromViewController:self
                                                 animated:YES
                                               completion:^(BOOL success, NSError * _Nullable error) {
                                                 if (!success) {
                                                   // there was a problem presenting the preferences
                                                 } else {
                                                   // next checkout will reflect the merchant's changes.
                                                 }
                                               }];

范围之外

以下功能由 SumUp APIs 处理。

社区

  • 有问题吗？ 通过发送电子邮件到 [email protected] 与我们的集成团队取得联系。
  • 发现了一个错误吗？ 打开一个问题。请尽可能提供更多信息。

改动日志

SumUp iOS SDK改动日志

授权

SumUp iOS SDK授权