Google Wallet API

Google Wallet API 允许您以编程方式创建、更新、列出和管理 Google Wallet 通行证。它支持与控制面板中的通行证构建器相同的操作。

使用它来发放会员卡、优惠、礼品卡、活动门票、登机牌、公交票和通用通行证，并向已保存在用户设备上的通行证推送实时更新。

前提条件：Google Wallet 配置

在为应用程序创建通行证之前，必须在 Pushwoosh 控制面板中为该应用程序配置 Google Wallet 发行者 ID 和服务帐户密钥。没有它们，create 和 update 请求将失败。请参阅 Android 的 Google Wallet 通行证配置。

基本 URL

https://apple-passkit.svc-nue.pushwoosh.com

所有端点都通过 HTTPS 提供服务。除非另有说明，请求和响应均使用 application/json。

身份验证

每个请求都必须包含一个 Authorization 标头，其中包含您的 Pushwoosh API 访问令牌：

Authorization: Token <api-token>

拥有该令牌的帐户必须拥有 applicationCode 引用的应用程序。对属于另一个帐户的应用程序的请求将返回 403 Forbidden。

约定

• 字段命名： JSON 字段使用 lowerCamelCase（例如，serialNumber、hexBackgroundColor、logoUrl）。
• 未填充的字段： 响应包含所有字段，即使为空或值为零。
• 身份： serialNumber 总是在创建通行证时由服务器分配。您在创建时发送的任何值都将被忽略。完整的 Google Wallet 对象 ID 是 {issuerId}.{serialNumber}。
• 图片： logoUrl 和 heroImageUrl 是指向 Google 获取的图片的公共 HTTPS URL，而不是上传的文件。
• 通行证样式： 通行证上必须设置且只能设置一个样式对象（generic、offer、loyalty、eventTicket、giftCard、flight 或 transit）。创建后样式不能更改。

错误响应

HTTP 状态	含义
400 Bad Request	无效参数——缺少必填字段或格式错误。
401 Unauthorized	Authorization 标头缺失或无效。
403 Forbidden	应用程序不属于调用者的帐户。
404 Not Found	未找到通行证、模板或应用程序。
503 Service Unavailable	服务已满负荷或暂时不可用。

端点

方法	路径	描述
POST	/api/google/pass/validate	验证通行证配置
POST	/api/google/pass/create	创建新的通行证对象并获取保存链接
POST	/api/google/pass/update/{serialNumber}	更新现有通行证；Google 将传递更改
GET	/api/google/pass/{applicationCode}/{serialNumber}/save-link	获取“添加到 Google Wallet”的保存链接
GET	/api/google/pass/{applicationCode}/{serialNumber}	获取单个通行证
GET	/api/google/passes	列出应用程序的所有通行证
POST	/api/google/pass/{applicationCode}/{serialNumber}/state	激活或作废通行证
DELETE	/api/google/pass/{applicationCode}/{serialNumber}	删除通行证
GET	/api/google/config	获取应用程序的 Google Wallet 配置
GET	/api/google/templates	列出可用的通行证模板
GET	/api/google/templates/{filename}	获取单个模板

创建通行证

在 Google Wallet 中创建通行证类和对象，然后返回服务器分配的序列号、完整的对象 ID 和一个“添加到 Google Wallet”的保存链接。

POST /api/google/pass/create

请求正文

参数	类型	是否必需	描述
pass	object	是	描述通行证的通行证对象。必须且只能设置一种样式。
userId	string	是	通行证发放给的 Pushwoosh User ID。
applicationCode	string	是	Pushwoosh 应用程序代码。

请求示例

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "hexBackgroundColor": "#3c414c",
    "logoUrl": "https://cdn.acme.com/logo.png",
    "loyalty": {
      "programName": "Acme Rewards",
      "accountName": "Jane Doe",
      "accountId": "1234567890",
      "pointsLabel": "Points",
      "pointsBalance": "1200",
      "rewardsTier": "Gold"
    },
    "barcode": {
      "format": "QR_CODE",
      "value": "1234567890"
    }
  }
}

响应

字段	类型	描述
serialNumber	string	服务器分配的已创建通行证的唯一身份。
objectId	string	完整的 Google Wallet 对象 ID：{issuerId}.{serialNumber}。
saveLink	string	“添加到 Google Wallet”链接：https://pay.google.com/gp/v/save/{jwt}。
message	string	结果消息。

响应示例

{
  "serialNumber": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "objectId": "XXXXXXXXXXXXXXX.XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "saveLink": "https://pay.google.com/gp/v/save/{jwt}",
  "message": "Pass created successfully"
}

验证通行证

根据 Google 的要求检查通行证配置，而无需创建它。在调用 create 之前很有用。

POST /api/google/pass/validate

请求正文

参数	类型	是否必需	描述
pass	object	是	要验证的通行证对象。

响应

字段	类型	描述
valid	boolean	通行证是否通过验证。
errors	array of strings	必须修复的阻塞性问题。
warnings	array of strings	非阻塞性建议。

更新通行证

使用新内容修补通行证对象。然后，Google 会将更新后的版本分发到保存了该通行证的每台设备。可以选择性地发送带有更新的 Android 通知。

POST /api/google/pass/update/{serialNumber}

路径参数

参数	类型	描述
serialNumber	string	创建通行证时返回的序列号。

请求正文

参数	类型	是否必需	描述
updates	object	是	包含新内容的通行证对象。样式不能更改。
applicationCode	string	是	Pushwoosh 应用程序代码。
notifyMessage	string	否	如果不为空，则向所有保存了该通行证的人推送带有此文本的 Android 通知。为空表示静默更新。
notifyOnUpdate	boolean	否	请求字段更新通知。只有 loyalty、eventTicket 和 flight 通行证会实际通知；其他样式接受该标志但从不发送通知。通知仅在相关开始时间的 3 小时内触发，并且 Google 将其限制为每张通行证每 24 小时最多 3 条通知。

两种更新通知方式

notifyMessage 会向所有保存了该通行证的人发送自定义 Android 通知，并适用于任何通行证样式。notifyOnUpdate 会请求 Google 发送其自己的字段更新通知，该通知仅对 loyalty、eventTicket 和 flight 通行证触发。

响应

字段	类型	描述
success	boolean	更新是否成功。
message	string	结果消息。

获取保存链接

为已创建的通行证返回一个“添加到 Google Wallet”的保存链接。通行证对象必须已存在（通过创建通行证创建）。

GET /api/google/pass/{applicationCode}/{serialNumber}/save-link

响应

字段	类型	描述
saveLink	string	https://pay.google.com/gp/v/save/{jwt}。

分享链接或将其渲染为二维码

将 saveLink 放在“添加到 Google Wallet”按钮后面，或使用任何 QR 库将其渲染为二维码。当用户打开它时，Google 会提示他们保存通行证并注册他们的设备以接收更新。

获取通行证

返回单个存储的通行证，包括其完整的通行证对象。

GET /api/google/pass/{applicationCode}/{serialNumber}

响应

返回 { "pass": { ... } }，一个通行证记录对象。

列出通行证

返回为应用程序存储的通行证的分页、排序列表。

GET /api/google/passes?applicationCode=XXXXX-XXXXX&page=0&perPage=20

查询参数

参数	类型	是否必需	描述
applicationCode	string	是	Pushwoosh 应用程序代码。
orderBy	string	否	排序字段：UPDATED（默认）或 CREATED。
orderDirection	string	否	排序方向：DESC（默认，最新在前）或 ASC。
page	integer	否	从零开始的页面索引。默认为 0。
perPage	integer	否	页面大小。0 或省略则使用服务器默认值。

响应

字段	类型	描述
passes	array of objects	当前页的通行证记录。
page	integer	返回的页面索引。
perPage	integer	此响应使用的页面大小。
total	integer	应用程序在所有页面上的通行证总数。

设置通行证状态

激活或作废通行证。已作废（非活动）的通行证会移动到用户 Google Wallet 中的已过期通行证部分；记录会保留，以便可以重新激活。

POST /api/google/pass/{applicationCode}/{serialNumber}/state

请求正文

参数	类型	是否必需	描述
active	boolean	是	true 将通行证设置为 ACTIVE；false 将其作废 (INACTIVE)。

响应

成功时返回一个空对象 {}。

删除通行证

在 Google 中作废通行证，并移除其在 Pushwoosh 中存储的记录。

DELETE /api/google/pass/{applicationCode}/{serialNumber}

已保存的通行证无法强制移除

Google 不允许移除已保存在用户设备上的通行证。删除操作会作废该通行证（它会移动到已过期通行证）并删除 Pushwoosh 记录。

响应

成功时返回一个空对象 {}。

获取配置

返回应用程序的 Google Wallet 配置状态。

GET /api/google/config?applicationCode=XXXXX-XXXXX

响应

字段	类型	描述
hasServiceAccount	boolean	是否配置了服务帐户密钥。
issuerId	string	已配置的 Google Pay & Wallet Console 发行者 ID。
serviceAccountEmail	string	已配置的服务帐户的 client_email。

模板

列出可用的示例通行证模板，或获取一个作为您可以作为起点的通行证对象。

GET /api/google/templates — 返回 { "templates": [ { "filename", "name", "description", "style" } ] }。

GET /api/google/templates/{filename} — 返回 { "template": { ...pass object... } }。

对象参考

通行证对象

字段	类型	描述
serialNumber	string	在创建时由服务器分配；用于标识通行证。
generic / offer / loyalty / eventTicket / giftCard / flight / transit	object	通行证样式。必须且只能设置一个。请参阅下面的样式对象。
hexBackgroundColor	string	卡片背景颜色，格式为 #rrggbb。
logoUrl	string	徽标图片的公共 HTTPS URL。对于会员卡和公交票是必需的。
heroImageUrl	string	宽幅横幅图片的公共 HTTPS URL。
barcode	object	通行证上显示的条形码。
textModules	array	详情视图中显示的文本模块。
links	array	详情视图中显示的链接模块。
expirationTime	string	Google 自动使通行证过期的 ISO 8601 时间。为空表示无过期时间。
appLink	object	应用链接：通行证正面的 CTA 按钮。
locations	array	触发地理围栏通知的位置（最多 10 个）。
holdersPolicy	string	谁可以保存通行证：ONE_USER_ALL_DEVICES（默认）、ONE_USER_ONE_DEVICE 或 MULTIPLE_HOLDERS。

通用对象

字段	类型	描述
cardTitle	string	必需。卡片顶部的发行者/计划名称。
header	string	必需。卡片的主标题。
subheader	string	副标题。
cardFields	array	最多 6 个固定在正面的文本模块（最多 3 行，每行 2 个）。

优惠对象

字段	类型	描述
title	string	必需。例如，全场八折。
provider	string	必需。商家名称。
details	string	优惠详情。
finePrint	string	条款和条件。
redemptionChannel	string	ONLINE、INSTORE、BOTH（默认）或 TEMPORARY_PRICE_REDUCTION。
issuerName	string	显示在 Google 的“由…发行”界面上；默认为 provider。

会员对象

字段	类型	描述
programName	string	必需。要求通行证上有 logoUrl。
accountName	string	卡片上显示的会员姓名。
accountId	string	卡片上显示的会员 ID。
pointsLabel	string	例如，积分。仅在有余额时显示。
pointsBalance	string	积分余额。
rewardsTier	string	例如，黄金会员。
rewardsTierLabel	string	等级旁边的标签；默认为 等级。
issuerName	string	默认为 programName。

活动门票对象

字段	类型	描述
eventName	string	必需。
venueName / venueAddress	string	场馆详情。
startDateTime / endDateTime	string	带偏移量的 ISO 8601（例如，2026-07-01T19:30:00+02:00）。
ticketHolderName / ticketNumber / ticketType	string	持票人和门票详情。
section / row / seat / gate	string	座位详情。
issuerName	string	默认为 eventName。

礼品卡对象

字段	类型	描述
merchantName	string	必需。
cardNumber	string	必需。
pin	string	卡片 PIN 码。
balance	string	十进制金额，例如 25.00。需要 balanceCurrency。
balanceCurrency	string	ISO 4217 货币代码，例如 USD。
issuerName	string	默认为 merchantName。

航班对象

字段	类型	描述
carrierIataCode	string	必需。2 个字母的 IATA 代码，例如 LX。
airlineName	string	航空公司显示名称。
flightNumber	string	必需。仅数字，例如 113。
originAirportCode / destinationAirportCode	string	必需。3 个字母的 IATA 代码。
originTerminal / originGate / destinationTerminal	string	航站楼和登机口详情。
departureDateTime	string	必需。出发机场当地时间，ISO 8601 不带偏移量（例如，2026-09-01T06:30:00）。
boardingTime / arrivalDateTime	string	相同的本地格式。arrivalDateTime 是目的地当地时间。
passengerName	string	必需。
confirmationCode / seatNumber / seatClass / boardingGroup	string	乘客详情。
issuerName	string	默认为 airlineName，然后是承运人代码。

公交对象

字段	类型	描述
transitType	string	必需。BUS、RAIL、TRAM、FERRY 或 OTHER。
transitOperatorName	string	必需。要求通行证上有 logoUrl。
passengerName	string	必需。
ticketNumber	string	票号。
tripType	string	ONE_WAY（默认）或 ROUND_TRIP。
legs	array	按旅行顺序列出的一个或多个公交路段。
issuerName	string	默认为 transitOperatorName。

公交路段对象

字段	类型	描述
originName / destinationName	string	必需。
departureDateTime / arrivalDateTime	string	ISO 8601；偏移量可选（省略时为当地时间）。
platform / coach / seat	string	登车详情。
fareName	string	例如，Anytime Single。

条形码对象

字段	类型	描述
format	string	QR_CODE、PDF_417、AZTEC、CODE_128、EAN_13 和其他 Google Wallet 条形码类型。
value	string	编码在条形码中的数据。
altText	string	条形码下方显示的文本。

文本模块对象

字段	类型	描述
id	string	模块的标识符。
header	string	模块标题。
body	string	模块文本。

链接模块对象

字段	类型	描述
uri	string	外部链接 URL。
description	string	详情视图中显示的链接标签。

应用链接对象

字段	类型	描述
uri	string	Web URL 或深层链接目标 URI。
androidPackageName	string	可选。设置后，将打开 Android 应用。
description	string	目标 URI 的内部描述（不是可见的按钮标签）；默认为 URI。

位置对象

字段	类型	描述
latitude	number	-90.0 到 +90.0。
longitude	number	-180.0 到 +180.0。

通行证记录对象

由 list/get 端点返回。

字段	类型	描述
serialNumber	string	通行证序列号。
objectId	string	完整的 Google Wallet 对象 ID {issuerId}.{serialNumber}。
cardTitle	string	通行证的显示标题/头部。
header	string	次要显示标题。
userId	string	通行证发放给的 Pushwoosh User ID。
createdAt / updatedAt	string	创建和最后更新的时间戳。
state	string	ACTIVE 或 INACTIVE。
style	string	generic、offer、loyalty、eventTicket、giftCard、flight 或 transit。
pass	object	完整的通行证对象，用于编辑。