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

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 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:

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

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:

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

Google Wallet Passes

Basic Pass Creation

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:

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

Style Groups (Dynamic Styling)

Style groups allow automatic style selection based on member points.

Step 1: Create Multiple Styles

# 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

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

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

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:

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

1. Member points are updated
2. System triggers pass rebuild
3. Push notification sent to registered devices
4. 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:

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

Best Practices

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