Wallet Service Documentation

Welcome to the Digital Membership Card Wallet Service documentation. This service enables organizations to create, distribute, and manage digital membership passes for both Apple Wallet and Google Wallet.

Overview

The Wallet Service is a Fastify-based REST API that integrates with:

• Apple Wallet (PassKit) - Native iOS wallet passes
• Google Wallet - Android wallet passes
• Salesforce - Member data synchronization
• Email (SMTP) - Pass distribution via email

Table of Contents

Section	Description
Getting Started	Quick setup instructions
API Reference	REST API endpoints and usage
Configuration	Environment variables and settings
Security	Security hardening and best practices
Architecture	System design and components
Development	Development workflow and guidelines
Testing	Testing strategies and commands

Getting Started

Prerequisites

Before you begin, ensure you have:

• Node.js v18+ installed
• npm v8+ or higher
• Access to Salesforce credentials (for member data)
• Apple Developer account with Pass Type ID (for Apple Wallet)
• Google Cloud project with Wallet API enabled (for Google Wallet)

Quick Start

1. Clone and install dependencies:

   npm install
   

2. Configure environment:

   cp example.env .env
   # Edit .env with your credentials
   

3. Start development server:

   npm run dev
   

4. Access the service:

   • API: http://localhost:3000
   • Swagger UI: http://localhost:3000/docs

Project Structure

wallet-service/
├── src/
│   ├── index.ts              # Application entry point
│   ├── server.ts             # Server bootstrap
│   └── app/
│       ├── app.ts            # Fastify application setup
│       ├── app.environment.ts # Environment configuration
│       └── views/            # Template files
│   └── lib/
│       ├── controllers/      # API route handlers
│       │   ├── apple.controller.ts    # Apple Wallet endpoints
│       │   ├── google.controller.ts   # Google Wallet endpoints
│       │   └── passes.controller.ts   # Pass management endpoints
│       ├── services/         # Business logic
│       │   ├── apple-passkit.service.ts
│       │   ├── google-wallet.service.ts
│       │   └── digital-membership.service.ts
│       ├── modules/          # Utility modules
│       ├── jobs/             # Background tasks
│       └── util/             # Helper functions
├── docs/                     # Documentation (you are here)
├── test/                     # E2E tests
└── build/                    # Compiled output

Key Features

Apple Wallet Integration

• Generate .pkpass files for iOS devices
• Automatic pass updates via Apple Push Notifications
• Device registration and lifecycle management
• Compliant with Apple's PassKit WebService specification

Google Wallet Integration

• Generate Google Wallet passes
• Callback handling for pass lifecycle events
• Secure message verification using Google's public keys

Member Data Synchronization

• Real-time member data from Salesforce
• Support for multiple membership types per member
• Automatic pass updates when member data changes

Pass Distribution

• Email delivery with pass attachments
• Direct download links
• Bulk pass generation

Support

For issues and questions:

• Check the API Reference for endpoint details
• Review Development Guide for contribution guidelines
• See Testing for debugging tips

---

Version: 0.1.0 | Last Updated: February 2026