WalletPasses

Apple Wallet and Google Wallet pass generation, management, and remote updates for Elixir.

Features

• Apple Wallet: Build signed .pkpass bundles, handle device registration callbacks, send silent APNs pushes
• Google Wallet: Create/update event ticket objects and classes, generate "Save to Google Wallet" URLs
• Platform-agnostic data model:PassData struct for content, separate Apple.Visual / Google.Visual for platform-specific styling
• Theme helper: Convert shared colors into platform-specific visual configs
• QR code generation: SVG and PNG output
• Ecto persistence: Separate per-platform tables with migration generator
• Optional add-ons: LiveView preview components, Oban background sync worker

Installation

Add wallet_passes to your list of dependencies in mix.exs:

def deps do
  [
    {:wallet_passes, "~> 0.1.0"},
  ]
end

Generate and run the database migrations:

$ mix wallet_passes.gen.migration
$ mix ecto.migrate

Configuration

# config/config.exs
config :wallet_passes,
  repo: MyApp.Repo,
  pass_data_provider: MyApp.WalletPassProvider,
  apple_pass_type_id: "pass.com.example.mypass",
  apple_web_service_url: "https://yourdomain.com/passes/apple"

# config/runtime.exs
config :wallet_passes,
  apple_team_id: System.get_env("APPLE_TEAM_ID"),
  apple_pass_type_cert: System.get_env("APPLE_PASS_TYPE_CERT"),
  apple_pass_type_key: System.get_env("APPLE_PASS_TYPE_KEY"),
  apple_wwdr_cert: System.get_env("APPLE_WWDR_CERT"),
  google_issuer_id: System.get_env("GOOGLE_WALLET_ISSUER_ID"),
  google_service_account_json: System.get_env("GOOGLE_WALLET_SERVICE_ACCOUNT_JSON")

Certificate/key values accept file paths, PEM strings, or base64-encoded values.

Quick Start

1. Implement the PassDataProvider

The library needs to look up pass data autonomously (e.g., when Apple requests an updated pass). Implement the behaviour:

defmodule MyApp.WalletPassProvider do
  @behaviour WalletPasses.PassDataProvider

  @impl true
  def build_pass_data(serial_number) do
    case MyApp.find_by_serial(serial_number) do
      nil -> {:error, :not_found}
      record ->
        {:ok, %{
          pass_data: %WalletPasses.PassData{
            serial_number: serial_number,
            event_name: record.event_name,
            holder_name: record.holder_name,
            primary_fields: [{"name", "Name", record.holder_name}],
            # ... more fields
          },
          apple: %WalletPasses.Apple.Visual{
            background_color: "#1A1A1A",
            foreground_color: "#FFFFFF",
            label_color: "#D4A843",
            icon_path: "/path/to/icon.png",
          },
          google: %WalletPasses.Google.Visual{
            background_color: "#1A1A1A",
            logo_uri: "https://example.com/logo.png",
          },
        }}
    end
  end
end

2. Generate passes

# Build an Apple .pkpass
{:ok, pkpass_binary} = WalletPasses.build_apple_pass(pass_data, apple_visual)

# Get a Google Wallet save URL
{:ok, url} = WalletPasses.google_save_url(pass_data, google_visual)

3. Mount the Apple callback router

Apple devices call back to your server to register for updates and fetch the latest pass. Mount the router in your Phoenix app:

# router.ex
forward "/passes/apple", WalletPasses.Apple.Router

4. Send push updates

WalletPasses.notify_apple_devices("SERIAL-NUMBER")

Theme Helper

Use the Theme struct to share colors across platforms:

theme = %WalletPasses.Theme{
  background_color: "#1A1A1A",
  foreground_color: "#FFFFFF",
  label_color: "#D4A843",
  logo_text: "My Event",
}

apple_visual = theme
  |> WalletPasses.Theme.to_apple_visual()
  |> struct!(icon_path: "/path/to/icon.png", strip_image_path: "/path/to/strip.png")

google_visual = theme
  |> WalletPasses.Theme.to_google_visual()
  |> struct!(logo_uri: "https://example.com/logo.png", hero_image_uri: "https://example.com/hero.png")

Optional Add-ons

Preview Components (Phoenix LiveView)

Add {:phoenix_live_view, "~> 1.0"} to your deps, then:

import WalletPasses.Preview.Components

<.apple_pass_preview pass_json={@apple_json} qr_svg={@qr_svg} />
<.google_pass_preview pass_object={@google_obj} qr_svg={@qr_svg} />

Background Sync (Oban)

Add {:oban, "~> 2.18"} to your deps, then:

# Sync specific passes
WalletPasses.Sync.sync(["SERIAL-1", "SERIAL-2"])

# Sync all passes in the database
WalletPasses.Sync.sync_all()

Why not passbook?

The passbook (ex_passbook) package is the only other Elixir library for .pkpass generation. Both it and this library shell out to openssl smime for PKCS#7 signing -- the signing approach is equivalent. However:

• Missing authenticationToken support -- passbook doesn't support the authenticationToken field, which is required for the pass update lifecycle (Apple devices use it to authenticate callback requests)
• URL camelization bug -- passbook has a known bug that mis-cases fields containing "url"
• Full lifecycle -- This library owns the entire pass lifecycle (generation, callbacks, push updates, Google Wallet API) rather than just .pkpass building

Pure-Erlang signing (eliminating the OpenSSL dependency) is a future goal. Contributing fixes upstream to passbook is also under consideration.

System Requirements

• OpenSSL -- required for .pkpass signing (used via System.cmd/3)
• PostgreSQL -- required for pass persistence (via Ecto)

License

MIT -- see LICENSE for details.