월렛 패스 API로 개인화 패스 발급하는 방법

월렛 패스 API를 쓰면 백엔드가 고객마다 이름, 잔액, 바코드, 위치가 담긴 패스를 만들고, 데이터가 바뀔 때마다 업데이트할 수 있습니다. 템플릿을 한 번 디자인하고, 사용자별 개인 값을 보내면, Apple Wallet용 설치 링크 또는 Google Wallet용 저장 링크가 돌아옵니다. 푸시 알림 API로 개인화 푸시 메시지를 보내는 것처럼, 패스도 고객마다 다른 값을 담습니다.

모든 팀에 API가 필요한 것은 아닙니다. 예시는 Pushwoosh 월렛 패스 API 기준이며, 모든 패스는 푸시, 이메일, 고객 여정을 움직이는 같은 User ID에 연결됩니다. API 우선 설계를 중시하는 한국 개발팀이라면, 이커머스 앱의 적립금이나 핀테크 앱의 멤버십 등급처럼 자체 서버에 있는 값을 패스에 그대로 반영하는 경우가 가장 흔한 출발점입니다.

API가 빌더보다 나은 경우

빌더는 패스를 디자인하고 소규모 또는 일회성 발송을 할 때 맞는 도구입니다. 패스가 자체 시스템에 있는 데이터에 의존하기 시작하면 API가 그 역할을 넘겨받습니다.

코드를 쓰기 전에 고객 여정 열부터 보세요. 트리거가 Pushwoosh가 이미 추적하는 고객 행동이라면, Customer Journey(고객 여정)의 Issue Wallet Pass 단계만으로 커스텀 코드가 필요 없는 경우가 많습니다.

템플릿과 개인 값

패턴은 두 플랫폼이 같습니다. 템플릿은 레이아웃, 브랜딩, 필드 구조를 담습니다. 사용자별 값은 발급 시점에 템플릿을 채웁니다.

개인 값은 고객마다 달라지는 부분입니다. 이름, 회원 번호, 포인트, 등급, 바코드 값, 만료일, 가장 가까운 매장 같은 것들이죠. 나머지는 모두 템플릿에서 오므로, 디자인을 바꿔도 연동 코드를 건드리지 않고 모든 새 패스에 적용됩니다. 예를 들어 설날이나 추석 시즌 디자인으로 바꿀 때도 개인 값은 그대로 둔 채 템플릿만 수정하면 됩니다.

회원 번호, 등급, 잔액 같은 개인 값은 그대로 개인정보입니다. 개인정보 보호에 매우 민감한 한국 시장에서는 연동 코드를 쓰기 전에 보안팀이 공급업체의 인증부터 확인하는 경우가 많고, 핀테크 앱이라면 이 검토가 거래 알림과 같은 수준으로 진행됩니다. Pushwoosh의 인증과 데이터센터 위치는 이 글의 마지막 섹션에 정리했습니다.

고객 여정에서 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 월렛 패스 설정 문서에 있습니다.

Google Wallet 흐름

Google Wallet API는 Google 패스의 같은 수명 주기를 다룹니다.

Google Pay & Wallet Console의 Issuer ID가 필요하며, 발급자 계정에 Pushwoosh 서비스 계정을 초대해야 합니다. 설정은 애플리케이션당 한 번입니다. 자세한 내용은 Google Wallet 설정 문서에 있습니다.

대규모 업데이트

API의 진가는 업데이트에서 드러납니다. 포인트 원장이나 예약 시스템이 값이 바뀌는 순간 패스를 업데이트하므로, 고객 Wallet 속 카드가 원본 데이터와 항상 일치합니다. 결제 직후 잔액이 바로 맞아야 하는 핀테크 앱이나, 이벤트 기간에 보상이 계속 바뀌는 게임 앱이라면 특히 중요한 부분입니다.

대규모 업데이트를 안전하게 돌리는 3가지 원칙:

• 현재 패스에서 시작하세요. Apple 업데이트는 전체 패스 객체를 받으므로, 패스를 가져와 바뀐 값만 수정하세요. Google 업데이트는 객체를 부분 수정(patch)합니다.
• 알림은 필드별로 정하세요. Apple에서는 변경 메시지가 있는 필드만 잠금 화면 알림을 띄웁니다. Google에서는 notifyOnUpdate가 Google 자체 알림을 요청하며, 멤버십, 이벤트 티켓, 항공권 패스에서만 패스당 24시간에 최대 3회 작동합니다. notifyMessage는 어떤 패스 유형이든 직접 작성한 Android 알림 문구를 보냅니다.
• 알림은 패스에 관한 내용으로만. Apple과 Google은 프로모션이 아니라 패스에 관한 알림만 허용합니다.

코드 예시

두 API 모두 기본 URL https://apple-passkit.svc-nue.pushwoosh.com을 쓰며, Pushwoosh API 액세스 토큰을 Authorization: Token <api-token> 헤더에 담습니다. 아래 요청 본문은 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가 맡습니다. 실수는 하나의 도구에 나머지 둘의 일까지 떠맡기는 것입니다.

모바일 게임 퍼블리셔를 예로 들면 이렇게 나뉩니다. 시즌 이벤트 패스의 디자인과 테스트는 빌더에서, 신규 가입이나 복귀 유저에게 주는 패스는 고객 여정에서, 게임 서버가 계산하는 보상과 등급은 API로 반영합니다. 유저 행동 기반 세그먼트도 같은 User ID 위에 있으므로, 패스 보유자에게 보내는 이벤트 알림과 업데이트 공지를 따로 맞출 필요가 없습니다.

Pushwoosh로 모든 패스를 대규모로 개인화하기

Pushwoosh는 네이티브 Apple Wallet과 Google Wallet 패스를 위한 비주얼 빌더, 고객 여정 단계, API를 별도의 패스 공급업체 없이 제공합니다. 각 패스는 푸시, 인앱, 이메일, SMS와 User ID를 공유하므로, 하나의 데이터가 모든 채널을 움직입니다. 고객 데이터는 ISO 27001:2022와 SOC 2 Type 2 인증을 받은 인프라에서 GDPR을 준수해 처리되며, 데이터센터는 EU와 미국에 있습니다.

대규모 개인화는 템플릿을 늘리는 문제가 아닙니다. 모든 Wallet 속 모든 카드가 하나의 원본 데이터를 그대로 반영하는 것입니다.

FAQ