Apple Pay的PassKit了解

对照

英文	中午
store card	购物卡
pass	凭证

• 和https://passkit.com 什么关系？

具体开发例子

参考 iOS PassKit Wallet 开发

1.Apple Pay 入门

使用者：购物时无需输入账单、送货和联系人详细信息 （保存在Wallet中） 开发者：无需负责管理和保护实际的信用卡和借记卡卡号（使用Touch ID为付款授权）

• Apple Pay (使用PassKit )
  • 可销售实物商品: 如食品杂货、服装和电器
  • 提供各种服务: 如俱乐部会员、酒店预订和活动门票
• App 内购买项目(使用StoreKit)
  • 可销售虚拟商品: 如适用于您的 App 的优质内容及订阅数字内容

参考《Apple Pay 编程指南》(Apple Pay Programming Guide),

开发前提条件

• 通过付款处理机构或网关设置一个帐户。
• 通过“证书、标识符和描述文件”（“Certificates, Identifiers & Profiles”）注册一个商家 ID
• 生成一个 Apple Pay 证书，用于加密和解密付款令牌。
• 在您的 App 中包括一个 Apple Pay 授权。
• 遵循《App 审核准则》(“App Review Guidelines”)第 29 节中列出的要求。

其他约束

• 支付供应商， 开发更简单 ?
• 如何显示 Apple Pay 按钮
• 如何显示付款单

Touch ID

Touch ID是苹果公司的一种指纹识别技术,硬件锁定,一机一Touch ID,只与一个处理器匹配

2.PassKit Framework

PassKit API支持Apple Pay的开发框架

• app增加Apple Pay，在不离开app情况下完成：
  • 购买实物商品: 如食品杂货、服装和电器
  • 购买各种服务: 如俱乐部会员、酒店预订和活动门票
  • 给慈善组织捐款：
• 管理钱包中凭证，增加、更新到钱包中：可以通过网络、邮件发送，设置呈现的时间、位置
  • 登机牌boarding passes
  • 票据tickets
  • 礼物卡gift cards
  • 会员卡、积分卡loyalty cards

包含2个主题

• Apple Pay
• Wallet
  其中列出了钱包使用的API: PKxxx 类族

2.1下载PassKit

访问Wallet and PassKit和 PassKit Web Service Reference 搜索passkit信息

Download Badges and Guidelines 下载 Add-to-Apple-Wallet.zip
Example Passes and Sample Code 下载 WalletCompanionFiles.zip

3.Wallet Developer Guide

3.1 钱包生态设计

• 创建、分发凭证
  商户Server负责分发pass给用户。苹果的mail/safari/icloud可以增加pass， 商户App可以用PassKit框架增加pass。
• 钱包管理凭证
  pass包含文本、图片、条码。 商户Server可以设置风格、图片、颜色、文本。钱包展现pass，用户可以管理（包括删除）pass。
• 商户app使用PassKit使用凭证
  app使用PassKit 框架提供API与凭证交互。app不要重复钱包的功能，最好实现钱包不具备的功能丰富用户体验（比如航班选座位，更新Pass）。 商户app未安装，对应的pass也要有效可用。app只能使用和其权限匹配的pass。
• 商户server更新凭证
  凭证信息变更，商户server推送通知到终端、app获取最新版本凭证（不是变更列表）。除了pass type ID/serial number外，其他信息都可以修改。 注意更新、新增的场景，不要让用户迷惑
  • 更新：修改车票、卡余额
  • 新增：面包券修改成饮料券，用户容易迷惑，面包券失效、新增饮料券
• 凭证兑现
  商户负责凭证有效期、使用次数，使用的效果（比如更新余额）。 几个不完整方案的场景：
  • 一次性优惠券
    凭证条码有唯一ID，商户DB保存该ID，用户使用时，扫描条码获取ID，从Server查询凭证是否有效。 删除过期的凭证需要用户同意。
  • 有余额的购物卡
    除了验证有效，还需要查询凭证的余额、记录交易、更新Server端凭证余额，Server更新钱包中凭证。（不要依赖凭证上信息，可能是过期的） 如果要验证用户是卡持有人，一种是凭证上有用户照片，另外一种是Server端存储照片app上显示，或者询问ID。
  • 会员卡
    全年使用相同的卡，偶尔展示活动信息。 除了可以和前面一样由Server验证，这里也可以直接保存到凭证中。 比如将扫描所需信息（账号、有效期）保存在凭证中，需要有加密签名，可以用来校验信息。 原因是存储在条码中信息不需改变（一次性优惠券、存储卡都需要改变信息）。
• 总结

PassKit	Apple	app
创建/分发Pass	提供SDK	- Mail/Safari增加Pass到钱包 - 调用PassKit增加Pass到钱包
展现/管理Pass	- 提供SDK - 钱包呈现，用户管理	- 设置风格、图片、颜色、文本 - ？
使用Pass	/	- 有效期、次数、范围 - 功能不要和钱包重复 - 未安装app，Pass也有效可用 - app权限和Pass类型匹配

3.2创建凭证

• 简单优惠券 可以使用多次，提供相同的信息
• 创建凭证包 凭证包中pass.json包括：凭证定义、图像（比如商标、图标）
  • 创建目录 xxx.pass
  • 下载WalletCompanionFiles.zip
  • 解压、拷贝SamplePasses中文件到 xxx.pass
• 设置 Pass Type Identifier / Team ID
  凭证都有一个和开发者相关联的凭证类型标识。到 Certificates, Identifiers & Profiles选择 Identifiers,再选Pass Type IDs. 在Keychain 中获取Team ID。 这个要付费申请开发者账号才能看到，Certificates包括：
  • 开发证书 （ Development Certificates ），主要是授权mac设备的开发权限
  • 发布证书 （Distribution Certificates ）， 主要是授权mac设置发布权限
    Identifiers 即“标识符”，约等于是身份证，用于创建：
  • App IDs 应用的唯一标示符，每一个应用的app id是不一样的
  • Pass Type IDs
  • Website Push IDs 将这2个ID填入xxx.pass/pass.json的passTypeIdentifier和teamIdentifier
• 签名、压缩凭证
  参考自动签名、压缩。 首先下载签名证书，再用xcode编译例子中signpass工程得到工具signpass

  signpass -p xxx.pass
  

  得到签名后的压缩凭证： xxx.pkpass

• 更新Offer
  修改pass.json中以下内容

    "description" : "Coupon for a free lollipop at Example Candy Store",
    "logoText" : "Example Candy Store",
   
    "coupon" : {
        "primaryFields" : [
            {
                "key": "offer",
                "value": "Free lollipop"
                "label": "On July 29"
            }
        ]
    },
  

• 展现凭证
  将xxx.pkpass拖入模拟器，

3.3凭证设计

• Pass Type Identifier and Serial Number 标识凭证 passTypeIdentifier ： 类型标识，建议用pass.域名逆序， 需要在Member Center注册。 通过证书控制APP可以访问哪些凭证。
  serialNumber ： 类型标识中唯一，PassKit不理解含义，唯一区分凭证即可。
  如果passTypeIdentifier和serialNumber相同，即使其他信息不同，也认为是同一个凭证。

一级信息

formatVersion ： 文件格式版本，目前为1 teamIdentifier： 必须和用来签名凭证的证书中 Team ID 匹配 organizationName ： 发放凭证的公司名称 description ： 描述信息， 用户可以区分同样类型中不同的凭证

样式设置外观

凭证样式styles 属于API，开发者无法增加、修改。 样式是另外一种分类方式

• boardingPass: 登机牌、火车票
• coupon: 优惠券、特价和其他折扣。
• eventTicket: 音乐会、电影、戏剧或体育赛事门票， 可以是一次性、也可以是多次使用。
• storeCard： 会员卡、折扣卡、积分卡和礼品卡。 可以有余额
• generic： 其他类，比如健身房会员卡、地铁票。

不同样式的布局、图片来源不同。 参考 样式对应布局关系 每一种凭证都预定义了一些区域，对应xxx.pass中不同字段。区域长度是有限的，过长会不显示。
xxx.pass中不要定义不显示的字段，如果需要可以定义在userInfo中。防止苹果修改布局导致突然显示原先隐藏的字段。

苹果Watch凭证

Watch上不显示Strip图像、缩略图。 不同的凭证在watch有不同显示方式。 在手机、手表上，用户使用方式也不同。参考手表人机接口

凭证上的文本区域

每个区域包含：

• key：唯一键， 比如boarding-gate
• label： 用户可读的键，比如Gate
• value： 用户可读键的值，比如F12
• 其他可选属性：value如何格式化

重要性：头区>主区>备区>辅助区。
当凭证堆在一起供选择时，只显示头区。

参考Field Dictionary Keys列出所有字段。

区域格式化

• alignment： 对齐方式
• dateStyle/timeStyle: 时间格式
• currencyCode/numberStyle: 数字格式

凭证背面提供附加文本信息

正面空间有限，信息简略。 背面信息backFields可以很长，用户可以滚动，还可以减小字体。 背面信息支持link，用户可以点击。

条码

barcodes：增加条码，用来关联商户服务器中对应记录 支持多种格式，手表不支持PKBarcodeFormatCode128，显示替代条码，如果没有则不显示条码。 提供替代文本，以便条码不可以扫描时手工输入。

条码中可以存储任何信息，比如签名信息，在无网络时，条码扫描仪直接校验。

条码中信息数量依赖条码格式、扫描条件。比如弱光条件下廉价扫描仪，需要实际测试验证可用。

凭证颜色

颜色默认设置，可以修改。

• backgroundColor： 背景颜色
• foregroundColor： 文本颜色
• labelColor： 正面label颜色

图像

可以伸缩适配分配到的区域。

锁屏信息

为方便使用，钱包在锁屏时可以立即显示凭证关联信息。
凭证提供时间relevantDate、位置locations，钱包基于这些信息显示，不要提供虚假信息操纵钱包显示。
只支持10个相关信息，可以更新凭证时修改。

还可以通过beacons（信标？）提供关联信息， 每个beacons有UUID，添加10个beacon。 可以一个UUID表示一个beacon一个位置，也可以一个UUID表示n个beancon（n个位置，比如一个连锁商店多个门面），这可以突破10个限制。 不同的样式，关联信息含义不同（比如位置，可能是100m内，也可能是1000m内）， 需要的关联信息也不同（比如登机牌需要日期）。 当然，所有样式都支持没有关联信息。

关联信息提供简单说明、或路径， 不要提供公司说明、使用说明。

本地化

凭证支持本地化：数字日期，字符串，图片 可以根据账号信息、用户首选位置设置，减少本地化数量，从而减少凭证大小。

使用字符串文件提供本地化信息，比如英语 en.lproj/pass.strings

签名加密、压缩

将xxx.pass中除清单、签名外所有文件用SHA-1签名，写入清单 manifest.json 从苹果申请的证书写入signature 最终压缩一个zip文件用来分发。

调试

如果不能加入钱包、显示，查看日志。 模拟器看syslog，真机看xcode的控制台。 常见的错误：

• JSON格式错误
• key、value拼写错误
• 凭证类型标识与证书不匹配
• 签名中没有WWDR中级证书

3.4 分发凭证

用户不需要商户app，通过Mail/Safari/iCloud添加凭证到钱包。 邮件附件方式简单，开发阶段方便使用。网站方式比较复杂，可以进行更多控制，比如用户登录。 app可以直接添加，提供更丰富的体验。参考PKAddPassButton添加凭证到钱包。

编程方式添加

添加一个凭证：

• 1.检查设备是否支持添加凭证： PKAddPassesViewController.canAddPasses
• 2.使用下载的签名、加密过的凭证实例化PKPass
• 3.使用PKPass创建PKAddPassesViewController
• 4.PKAddPassesViewController显示，用户同意或拒绝添加凭证， 回调

添加多个凭证（比如联程登机牌）：

• 1.创建PKPass对象列表
• 2.调用PKPassLibrary.addPasses

WEB方式

有多种方式，有的自动处理凭证，有的需要下载再处理，推荐方案：

• safari中打开网页，app将控制权转给safari， 自动添加
• 使用 SFSafariViewController 展示内容，自动添加
• 使用WKWebView 展示， 需要app下载、添加

3.5 更新凭证

线下状态改变，需要更新凭证， 所有凭证的信息都可以改变，除了token和serial number。

通信

更新凭证需要终端、苹果server、商户server协同：

• 1.终端安装支持更新的凭证，向商户server订阅获取更新
• 2.有更新，商户server发送push通知
• 3.终端收到通知，向商户server获取更新列表
• 4.终端箱商户server获取改变的凭证最新版本

凭证内置webServiceURL，钱包用来访问商户server
默认是https，开发者设置可以打开http。 商户server通过Device library identifier、authenticationToken校验请求是否授权。 前者是PassKit指定的终端设备、商户server之间的共享密钥， 终端与不同的server有不同ID，防止server记录终端上安装的凭证列表。 后者内置在凭证中，表示请求来自安装证书的用户，而不是第三方。

商户server需要记录：

• 终端，由Device library ID标识， 还有push令牌
• 凭证，由pass type ID/序号标识，更新相关信息
• 订阅信息，终端和凭证双向关系互查，这是n to m关系

终端订阅

当终端订阅时，向webServiceURL发送POST请求，商户server完成：

• 验证Authentication token是否是凭证中内置的？
• 存储终端信息：device lib ID、push token
• 存储凭证信息
• 存储订阅信息

当终端发送DELETE请求时，表示去订阅，商户server可以立刻删除这些信息。

通知终端

当凭证变更后，商户server向所有订阅该凭证的终端推送通知。

• 更新凭证信息
• 获取订阅的终端
• 获取终端的push令牌
• 用令牌发送空消息给终端： 推送消息不可靠

终端请求修改Serial Number

终端收到推送通知，向商户server请求特定时间点（更新tag）之后修改的凭证所有序列号 商户server返回最新的更新tag、其后的所有序列号。 server能比较不同更新tag之间先后关系

终端请求最新版凭证

终端请求指定序列号下所有变更过的凭证的最新版本，

终端显示变更信息

终端比较凭证中修改的区域，如果修改区域有变更消息，终端显示该变更消息，该消息会通知用户立刻阅读。

最佳实践

• 妥善保存私钥、证书
• 商户server不要保存私钥、证书， 由另外一个内部server生成签名后的凭证给商户server
• 信息都在url中，部分限制URL长度系统有问题
• 更新凭证时不要修改授权令牌。因为更新可能失败，所有令牌都可能用。

3.6 APP与凭证互动

打开Passbook功能

访问凭证

PKPassLibrary凭证库， PKPass凭证，PKAddPassesViewController 视图控制器

校验Pass库是否可用

PKPassLibrary.isPassLibraryAvailable

检查凭证是否在库中

获取凭证

PKPassLibrary.passes获取app可以访问的所有凭证，无序，由app排序。

读取凭证

PKPassLibrary.passWithPassTypeIdentifier(serialNumber)

增加新凭证

修改凭证

终端上不能直接修改凭证，修改内容会导致签名失效，凭证需要用商户的私钥签名，app中不能存有私钥。 必须通知商户server，由server更新凭证并签名，app再下载凭证，使用replacePassWithPass更新。

删除凭证

PKPassLibrary.removePass 凭证属于用户，删除凭证必须是用户动作。没有用户授权，及时过期、失效，app也不能删除。

3.7 奖励注册

创建一个含有用户个人信息的凭证， 个性化凭证可以像其他凭证一样分发，安装时：

• 钱包提供一个注册表格搜集用户信息
• 用户填写完，钱包将用户数据、个性化token传到商户server
• 商户server为用户创建一个账号
• 商户server使用凭证证书签名个性化token，返回签名后token
• 钱包校验token
• 钱包请求个性化凭证
• 商户server返回个性化凭证
• 钱包删除原始凭证，安装新的个性化凭证

设置凭证个性化

创建分发个性化凭证， web服务端点可以返回个性化凭证

创建个性化凭证

在标准的凭证包中包括：

• personalization.json 文件保存注册表中用户个性化信息
• personalizationLogo@XX.png

4.PassKit Package Format Reference

包结构

一级目录含有：

• background.png 凭证正面背景
• footer.png 凭证正面靠近条形码的图像
• icon.png 凭证的图标
• logo.png 凭证左上角
• manifest.json 清单
• pass.json 凭证信息
• signature PKCS＃7签名
• strip.png 凭证正面的主要字段后面图像
• thumbnail.png 凭证正面的缩略图

  顶级键

  低级键

  字段字典

5.Apple Pay

配置开发环境

注册商家ID 创建支付处理证书

创建支付请求

PKPaymentRequest实例完成支付请求，包括支付项目清单、可选物流列表、收货地址、商户信息。

用户是否可以付款

检查网络：PKPaymentAuthorizationViewController.canMakePaymentsUsingNetworks 检查硬件、家长控制：canMakePayments ，返回NO则不显示Apply Pay按钮 用户按下Apple Pay按钮，就必须开始付款授权过程，其他过程(比如输入优惠码)必须在之前完成。

WEB桥接

基于Web的界面来购买商品和服务，必须请求从Web界面移至本机iOS代码。

付款请求包括货币和地区信息

支付请求中的所有汇总金额都使用相同的货币，使用三字符ISO货币代码，例如USD。 付款请求的国家代码表示购买发生的国家或购买地点。使用两个字符的ISO国家代码，例如US。 付款申请中商家ID必须与应用授权中的某个商家ID匹配。

付款请求有一个付款汇总项目清单

比如小计，任何折扣，运费，税金和总计

运输方式是特殊付款汇总项目

发货方式包括标准发货、次日发货，成本，所以有一个detail属性

支持的支付方式

supportedNetworks 数组表示支持的支付方式。merchantCapabilities比特表示协议(3DS/EMV)

物流、发票信息

requiredBillingAddressFields和requiredShippingAddressFields

附加信息

applicationData 存储其他支付相关信息

授权支付

支付授权2个功能：

• 让用户填写或选择发票、物流信息。 会回调app，比如更新费用
• 用户授权支付订单。 会回调app，支付令牌

app回调更新物流、价格

创建支付令牌

用户授权时，苹果服务器会创建支付令牌， 回调app时，app可以将令牌和其他信息发往商户server

• 框架将支付请求发给 Secure Element， 获取令牌化的支付卡号
• Secure Element将卡、商加密，返回框架， 框架将其发往苹果server
• 苹果server用商户证书加密该数据，
• 回调app时，将信息传递给商户server

订单确认

支付

支付步骤：

• 将付款信息及其他信息发送到商户server
• 验证付款数据的散列和签名
• 解密加密的付款数据
• 将支付数据提交给支付处理网络
• 将订单提交给您的订单跟踪系统

6.其他渠道

• Stripe
• Ping++
• BeeCloud

  功能

• 支付方式
  • 手机app （iOS/Android/H5）
  • PC网页
  • QR扫码
• 支付场景
  • 支付
  • 查询
  • 退款
  • 红包
  • 企业付款
  • 账户系统（余额、优惠券）
  • 订阅支付（定时自动扣款）
  • 分期支付
• 开发
  • SDK
  • Live&Sandbox

特性

• 服务稳定
• 支持参数安全
• 客户端SDK安全可靠