如何通过 API 发放个性化钱包卡券：出海团队开发指南

钱包卡券 API 让您的后端为每位海外用户生成专属卡券，包含其姓名、余额、条形码和地点，并在数据变化时随时更新。您只需设计一次模板，按用户提交个人字段值，就能拿到 Apple Wallet 的安装链接或 Google Wallet 的保存链接。

并不是每个团队都需要 API。对于习惯 API 优先、已经通过 FCM/APNs 接入推送的出海技术团队，它往往是最自然的接入方式。示例基于 Pushwoosh Wallet passes API：每张卡券都绑定一个 User ID，同一个 User ID 也驱动着您的推送、邮件和用户旅程。

API 何时比编辑器更合适

编辑器适合设计卡券，以及小规模或一次性的发放。当卡券依赖的数据存放在您自己的系统里时，就该由 API 接手。

写代码之前，先看用户旅程这一列。如果触发条件是 Pushwoosh 已经在追踪的用户行为，Customer Journey 中的 Issue Wallet Pass（发放钱包卡券）步骤往往就能省掉自定义代码。

模板与个人字段

两个平台的模式相同。模板负责版式、品牌元素和字段结构，个人字段值在发放时填入。

个人字段就是因人而异的内容：姓名、会员号、积分、等级、条形码值、有效期、最近的门店。其余一切来自模板，所以修改设计会自动应用到每一张新卡券，无需改动您的集成。对于跨境电商的会员计划或出海游戏的赛季通行证，这意味着按市场调整卡面时，后端代码可以保持不动。

在用户旅程中，Issue Wallet Pass 步骤接收 Apple 和 Google 的卡券活动（apple_campaign_id、google_campaign_id）以及要填入的 personal_values。1 个步骤就能向同一个 User ID 同时发放两个版本。

Apple Wallet 接入流程

Apple 卡券编辑器能做的一切，在 Apple Wallet PassKit API 中同样可以完成：创建、更新、列出、下载和删除卡券。

典型的集成分 4 步。

每个应用需要一个 Pass Type ID 证书（.p12）和一个 Apple Developer 账号（每年 $99）。配置方法见 iOS Wallet 卡券配置文档。

Google Wallet 接入流程

Google Wallet API 为 Google 卡券覆盖同样的生命周期。

对出海团队来说，Google Wallet 卡券和 FCM 推送面向的都是海外 Android 用户。两者共用同一个 User ID 和同一套用户分群，所以收到 FCM 推送的那批用户，也可以直接成为卡券的发放对象。

您需要在 Google Pay & Wallet Console 中获取一个 Issuer ID，并把 Pushwoosh 的服务账号邀请到您的 issuer，每个应用只需设置一次。配置方法见 Google Wallet 配置文档。

大规模更新

更新才是 API 真正发挥价值的地方。积分账本或预订系统可以在数值变化的那一刻更新卡券，让用户钱包里的卡与您的数据源始终一致。即便在双十一或黑五这类全球大促期间余额频繁变动，卡面也能跟上。

保证大批量更新安全的 3 条规则：

• 从当前卡券出发。 Apple 的更新需要完整的卡券对象，所以先获取卡券，只修改发生变化的值。Google 的更新则是对对象打补丁。
• 逐个字段决定是否提醒。 在 Apple 上，只有设置了变更消息（change message）的字段才会显示锁屏提醒。在 Google 上，notifyOnUpdate 会请求 Google 发送它自己的提醒，仅适用于会员卡、活动门票和登机牌，每张卡券 24 小时内最多 3 条。notifyMessage 则可以在任何卡券类型上发送您自定义的 Android 通知文案。
• 提醒只谈卡券本身。 Apple 和 Google 只允许与卡券相关的通知，不允许促销。

对金融科技出海 App 而言，交易完成后更新卡券上的余额或状态，正是典型的卡券相关通知。同一个交易事件还可以触发一条交易通知推送，用户在钱包和通知栏里看到的是同一份数据。

代码示例

两个 API 都使用基础 URL https://apple-passkit.svc-nue.pushwoosh.com，并在 Authorization: Token <api-token> 请求头中携带您的 Pushwoosh API 访问令牌。下面的请求体取自 API 参考文档中的示例。

创建 Apple Wallet 卡券： POST /api/pass/create。响应返回卡券的 serialNumber。

{
  "applicationCode": "XXXXX-XXXXX",
  "userId": "user-123",
  "pass": {
    "description": "Acme loyalty card",
    "logoText": "Acme",
    "backgroundColor": "rgb(60, 65, 76)",
    "foregroundColor": "rgb(255, 255, 255)",
    "labelColor": "rgb(255, 255, 255)",
    "storeCard": {
      "primaryFields": [
        { "key": "balance", "label": "BALANCE", "value": "1200 pts" }
      ],
      "secondaryFields": [
        { "key": "member", "label": "MEMBER", "value": "Jane Doe" }
      ]
    },
    "barcodes": [
      {
        "format": "PKBarcodeFormatQR",
        "message": "1234567890",
        "messageEncoding": "iso-8859-1"
      }
    ]
  },
  "images": [
    { "imageType": "icon", "data": "<base64>", "contentType": "image/png" },
    { "imageType": "logo", "data": "<base64>", "contentType": "image/png" }
  ]
}

创建 Google Wallet 卡券： POST /api/google/pass/create。响应返回 serialNumber 和 saveLink。

{
  "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"
    }
  }
}

更新时，带上序列号发送新内容：Apple 用 POST /api/pass/update/{serialNumber}，Google 用 POST /api/google/pass/update/{serialNumber}。

编辑器、API 还是用户旅程：一条简单规则

用编辑器做设计和测试。当触发条件是 Pushwoosh 中已有的用户事件，比如注册或首单时，用用户旅程步骤。当触发条件或数据存放在您的后端时，用 API。

大多数团队最终 3 种都会用到，这很正常：编辑器负责设计，用户旅程负责生命周期中的关键时刻，API 负责实时余额和状态。真正的错误是强迫其中 1 种去做其他两种的工作。

用 Pushwoosh 大规模个性化每一张卡券

Pushwoosh 为原生 Apple Wallet 和 Google Wallet 卡券提供可视化编辑器、用户旅程步骤和 API，中间没有额外的卡券服务商。每张卡券与您的推送、应用内消息、邮件和短信共用 1 个 User ID，1 套数据驱动所有渠道。平台已通过 ISO 27001:2022 和 SOC 2 Type 2 认证，符合 GDPR 要求，数据中心位于欧盟和美国。

大规模个性化的关键不在于更多模板，而在于 1 个唯一的数据源，让每个钱包里的每张卡都如实反映它。

FAQ