Pass Generation

Learn how to create and customize Apple Wallet and Google Wallet passes.

Overview

WalletPass.ai supports two wallet platforms:

Apple Wallet - Generates signed .pkpass files
Google Wallet - Creates JWT-based passes with "Save to Wallet" URLs

Apple Wallet Passes

Basic Pass Creation

bash

curl -X POST https://generate.walletpass.ai/v1/passes/create-from-member \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "member_id": "MEMBER-001",
    "pass_type": "apple",
    "company_name": "My Company"
  }'

Pass expiration

If you do not provide an expiration date, the pass will not expire. The service must not add an expirationDate to the pass in that case.
If you do provide an expiration date (e.g. in pass style or request), it will be set on the pass. See APPLE_PASS_EXPIRATION.md for the exact rules.

Pass Structure

Apple Wallet passes include:

Barcode/QR Code - Generated from member ID
Primary Fields - Main information (tier, points, etc.)
Secondary Fields - Additional details
Back Fields - Information shown when pass is flipped
Images - Logo, icon, strip images
Colors - Brand colors for customization

Pass Styles

Create reusable pass styles for consistent branding:

bash

curl -X POST https://generate.walletpass.ai/v1/pass-styles \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "name": "Premium Style",
    "brand_colors": {
      "foreground_color": "rgb(255,255,255)",
      "background_color": "rgb(255, 107, 53)",
      "label_color": "rgb(255,255,255)"
    },
    "barcode": {
      "format": "PKBarcodeFormatQR"
    },
    "primary_fields": [
      {
        "key": "tier",
        "label": "Membership",
        "value": "{tier}"
      }
    ]
  }'

Using Pass Styles

bash

curl -X POST https://generate.walletpass.ai/v1/passes/create-from-member \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "member_id": "MEMBER-001",
    "pass_type": "apple",
    "company_name": "My Company",
    "pass_style_id": "style-uuid-here"
  }'

Dynamic Fields

Pass styles support dynamic field values using placeholders:

{tier} - Member's current tier
{points} - Member's current points
{member_name} - Member's name
{member_id} - Member's ID

Example:

json

{
  "primary_fields": [
    {
      "key": "points",
      "label": "Points",
      "value": "{points}"
    },
    {
      "key": "tier",
      "label": "Membership",
      "value": "{tier}"
    }
  ]
}

Google Wallet Passes

Basic Pass Creation

bash

curl -X POST https://generate.walletpass.ai/v1/passes/create-from-member \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "member_id": "MEMBER-001",
    "pass_type": "google",
    "company_name": "My Company",
    "external_id": "EXT-MEMBER-001"
  }'

Google Wallet Features

JWT-Based - Uses JWT tokens for "Save to Wallet" functionality
External ID - Separate ID for barcode/display (different from member_id)
Loyalty Class - Uses existing loyalty class from Google Wallet account
Real-Time Updates - Passes update automatically when member data changes

Pass URL

The response includes a pass_url that can be:

Opened in a browser on Android device
Embedded in your app
Sent via SMS/email

Example response:

json

{
  "status": "success",
  "data": {
    "pass_id": "google-pass-id",
    "pass_url": "https://pay.google.com/gp/v/save/...",
    "pass_type": "google"
  }
}

Auto Linked Passes

You can send a second pass (e.g. a bonus or gift card) to a member who already has a primary Google Wallet loyalty pass. The new pass is auto-linked to the primary pass and appears grouped with it in Google Wallet.

Requirements:

The member must already have a Google Wallet loyalty pass (created via the API with the same member_id).
No API key required for the demo endpoint.

Create and link a bonus pass:

bash

curl -X POST https://generate.walletpass.ai/demo/google/linked-pass \
  -H "Content-Type: application/json" \
  -d '{
    "member_id": "MEMBER-001",
    "member_name": "Member 001",
    "header_title": "Bonus pass",
    "card_title": "WalletPass.ai"
  }'

Request body:

Field	Required	Description
`member_id`	Yes	Same member ID as the primary loyalty pass
`member_name`	No	Display name (default: "Member")
`member_email`	No	Account email
`card_title`	No	Issuer/card title (default: "WalletPass.ai")
`header_title`	No	Pass title, e.g. "Bonus pass" or "Gift card" (default: "Bonus pass")
`barcode_value`	No	Barcode/QR value (default: "LINKED-{member_id}")
`qr_code_value`	No	QR code value (e.g. coupon code, reward code). If set, overrides `barcode_value`; if empty, `barcode_value` or "LINKED-{member_id}" is used.
`pass_style_id`	No	UUID of a pass style for logo, hero image, and background color. Use the same style as your main pass or a dedicated style for the bonus pass.
`tenant_id`	When using style	Tenant UUID where the style was created. Required when `pass_style_id` is set (use the same API key/tenant as when creating the style).

Response: The linked pass is created and attached to the primary pass. The response includes pass_url so the user can add the new pass manually if it does not appear automatically.

json

{
  "status": "success",
  "message": "Linked pass created and attached to primary loyalty pass...",
  "data": {
    "linked_object_id": "3388000000023035616.MEMBER-001_linked",
    "primary_member_id": "MEMBER-001",
    "pass_url": "https://pay.google.com/gp/v/save/...",
    "pass_type": "google"
  }
}

GET /demo/google/linked-pass returns usage information (method and body parameters).

Style Groups (Dynamic Styling)

Style groups allow automatic style selection based on member points.

Step 1: Create Multiple Styles

bash

# Bronze style (0-100 points)
curl -X POST https://generate.walletpass.ai/v1/pass-styles \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "name": "Bronze",
    "brand_colors": {
      "background_color": "rgb(205, 127, 50)"
    }
  }'

# Silver style (101-200 points)
curl -X POST https://generate.walletpass.ai/v1/pass-styles \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "name": "Silver",
    "brand_colors": {
      "background_color": "rgb(192, 192, 192)"
    }
  }'

Step 2: Create Style Group

bash

curl -X POST https://generate.walletpass.ai/v1/style-groups \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "name": "Tier Colors",
    "rules": [
      {
        "pass_style_id": "bronze-style-uuid",
        "min_points": 0,
        "max_points": 100
      },
      {
        "pass_style_id": "silver-style-uuid",
        "min_points": 101,
        "max_points": 200
      }
    ]
  }'

Step 3: Attach to Member

bash

curl -X PUT https://member.walletpass.ai/v1/members/MEMBER-001 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "style_group_id": "style-group-uuid"
  }'

Step 4: Create Pass with Style Group

bash

curl -X POST https://generate.walletpass.ai/v1/passes/stylegroup/create-from-member \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_your_api_key" \
  -d '{
    "member_id": "MEMBER-001",
    "pass_type": "apple",
    "company_name": "My Company",
    "style_group_id": "style-group-uuid"
  }'

The system automatically selects the style based on the member's current points.

Pass Assets

Apple Wallet Assets

Logo - 100x100 or 320x100 PNG
Icon - 29x29, 58x58, 87x87 PNG (@1x, @2x, @3x)
Strip - ~624x245 PNG (displayed at top of pass)

Google Wallet Assets

Logo - ~660x660 PNG/JPEG
Hero - ~1032x336 PNG/JPEG

Asset Configuration

Assets can be configured in pass styles:

json

{
  "assets": {
    "apple": {
      "logo": "logo.png",
      "strip": "strip.png"
    },
    "google": {
      "logo": "logo.png",
      "hero": "hero.png"
    }
  }
}

Pass Updates

Automatic Updates

When member data changes (points, tier, etc.), passes automatically update on devices:

Member points are updated
System triggers pass rebuild
Push notification sent to registered devices
Devices fetch updated pass

Manual Pass Rebuild

Passes are automatically rebuilt when:

Member points change
Member tier changes
Member information is updated

Multi-Pass Support

Members can have multiple passes:

Multiple Apple Wallet passes
Multiple Google Wallet passes
Different pass types (loyalty, coupon, etc.)

All passes are linked to the member and shown in the member response:

json

{
  "member_id": "MEMBER-001",
  "passes": [
    {
      "pass_id": "pass-1",
      "pass_type": "apple"
    },
    {
      "pass_id": "pass-2",
      "pass_type": "google"
    }
  ]
}

Best Practices

Use Pass Styles - Create reusable styles for consistency
Use Style Groups - For dynamic styling based on points/tiers
External IDs - Use meaningful external IDs for Google Wallet
Asset Optimization - Optimize images for faster loading
Test Passes - Always test passes on real devices before production

Pass Generation ​

Overview ​

Apple Wallet Passes ​

Basic Pass Creation ​

Pass expiration ​

Pass Structure ​

Pass Styles ​

Using Pass Styles ​

Dynamic Fields ​

Google Wallet Passes ​

Basic Pass Creation ​

Google Wallet Features ​

Pass URL ​

Auto Linked Passes ​

Style Groups (Dynamic Styling) ​

Step 1: Create Multiple Styles ​

Step 2: Create Style Group ​

Step 3: Attach to Member ​

Step 4: Create Pass with Style Group ​

Pass Assets ​

Apple Wallet Assets ​

Google Wallet Assets ​

Asset Configuration ​

Pass Updates ​

Automatic Updates ​

Manual Pass Rebuild ​

Multi-Pass Support ​

Best Practices ​

Pass Generation

Overview

Apple Wallet Passes

Basic Pass Creation

Pass expiration

Pass Structure

Pass Styles

Using Pass Styles

Dynamic Fields

Google Wallet Passes

Basic Pass Creation

Google Wallet Features

Pass URL

Auto Linked Passes

Style Groups (Dynamic Styling)

Step 1: Create Multiple Styles

Step 2: Create Style Group

Step 3: Attach to Member

Step 4: Create Pass with Style Group

Pass Assets

Apple Wallet Assets

Google Wallet Assets

Asset Configuration

Pass Updates

Automatic Updates

Manual Pass Rebuild

Multi-Pass Support

Best Practices