Google Wallet Node.js API

A Node.js REST API project for generating Google Wallet student passes using JWT.

What is Google Wallet?

Google Wallet is a digital wallet platform developed by Google that allows users to store and manage various types of digital passes, including:

• Event Tickets - Concert tickets, sports events, theater shows
• Student Passes - Student identification cards with access control
• Boarding Passes - Flight tickets and travel documents
• Loyalty Cards - Membership and reward cards
• Gift Cards - Digital gift cards for various retailers

This API specifically focuses on generating Student Passes that can be saved directly to a user's Google Wallet app on their Android device. The passes are generated using JWT (JSON Web Tokens) signed with your Google Wallet service account credentials.

Users can save these passes to their Google Wallet by clicking a generated URL, which opens the Google Wallet app and adds the pass to their digital wallet collection.

Features

• REST API for Google Wallet student pass generation
• JWT-based Google Wallet integration
• Clean MVC architecture (controllers, routes, utils, middleware)
• Request validation middleware
• Environment-based configuration

Project Structure

src/
├── app.js                 # Main application entry point
├── controllers/           # Route controllers
│   └── studentPassController.js
├── routes/               # API routes
│   ├── index.js
│   └── studentPassRoutes.js
├── middleware/           # Custom middleware
│   └── validation.js
└── utils/               # Utility functions
    └── googleWallet.js

Prerequisites

• Node.js (v14 or higher)
• Google Cloud Project with Wallet API enabled
• Service account with appropriate permissions

Installation

1. Clone or download this project

2. Install dependencies:

npm install

This will:

• Download all required Node.js modules listed in package.json
• Create a package-lock.json file with exact version information
• Install the dependencies in the node_modules/ folder

What gets installed:

• dotenv - For loading environment variables
• express - Web framework for the API
• jsonwebtoken - For signing JWT tokens for Google Wallet
• moment - For date/time handling

3. Configure environment variables:

cp .env.example .env

4. Edit .env file with your Google Wallet credentials:

GOOGLE_WALLET_ISSUER_ID=your_issuer_id_here
GOOGLE_WALLET_CLIENT_EMAIL=your_service_account_email@project-id.iam.gserviceaccount.com
GOOGLE_WALLET_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYOUR_PRIVATE_KEY_HERE\n-----END PRIVATE KEY-----\n"
BASE_URL=https://yourdomain.com
PORT=3000

Files Generated After Installation

After running npm install, you will see:

• node_modules/ - Folder containing all installed packages
• package-lock.json - Lock file with exact versions of installed dependencies (important for consistent deployments)

Important Git Configuration:

• node_modules/ is in .gitignore - never commit this folder
• .env is in .gitignore - never commit your credentials
• package-lock.json SHOULD be committed - ensures consistent installations
• Service account JSON files are in .gitignore - never commit these

Getting Google Wallet Credentials

Step-by-Step Guide to Get Environment Variables

1. Create a Google Cloud Project

1. Go to Google Cloud Console
2. Click on the project dropdown at the top
3. Click "New Project"
4. Enter a project name (e.g., "Google Wallet Student Pass")
5. Click "Create"
6. Wait for the project to be created (1-2 minutes)
7. Select your new project from the dropdown

2. Enable Google Wallet API

1. In the Google Cloud Console, search for "Google Wallet API" in the search bar
2. Click on "Google Wallet API" from the results
3. Click the "Enable" button
4. Wait for the API to be enabled

3. Create a Service Account

1. Navigate to IAM & Admin > Service Accounts
2. Click "Create Service Account"
3. Enter a service account name (e.g., "google-wallet-service")
4. Click "Create and Continue"
5. Skip adding roles for now (or add "Service Account Token Creator" if needed)
6. Click "Done"
7. Click on the newly created service account
8. Go to the "Keys" tab
9. Click "Add Key" > "Create new key"
10. Select "JSON" as the key type
11. Click "Create"
12. The JSON key file will be downloaded automatically

4. Extract Environment Variables from Service Account JSON

Open the downloaded JSON file. You'll need these values:

For GOOGLE_WALLET_CLIENT_EMAIL:

• Look for "client_email" field
• Copy the email address (e.g., google-wallet-service@your-project-id.iam.gserviceaccount.com)

For GOOGLE_WALLET_PRIVATE_KEY:

• Look for "private_key" field
• Copy the entire key including the -----BEGIN PRIVATE KEY----- and -----END PRIVATE KEY----- parts
• Replace literal \n characters with actual newlines when adding to .env file

5. Get Your Issuer ID

1. Go to Google Pay & Wallet Console
2. Sign in with your Google account
3. Click "Get Started" if it's your first time
4. Navigate to the "Issuers" section
5. Click "Add Issuer" if you don't have one
6. Fill in the issuer details:
   • Issuer Name: Your organization name
   • Issuer ID: This will be auto-generated (e.g., 3388000000000000000)
7. Save the issuer
8. Copy the Issuer ID from the issuer details page

For GOOGLE_WALLET_ISSUER_ID:

• This is the numeric ID assigned to your issuer (e.g., 3388000000000000000)

6. Configure BASE_URL

1. Decide on your domain where this API will be hosted
2. For local development, you can use http://localhost:3000
3. For production, use your actual domain (e.g., https://api.yourdomain.com)

For BASE_URL:

• Use your domain or localhost URL

7. Add Variables to .env File

Create a .env file in your project root and add:

GOOGLE_WALLET_ISSUER_ID=3388000000000000000
GOOGLE_WALLET_CLIENT_EMAIL=google-wallet-service@your-project-id.iam.gserviceaccount.com
GOOGLE_WALLET_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...\n-----END PRIVATE KEY-----\n"
BASE_URL=http://localhost:3000
PORT=3000

Important Notes

• Keep your service account JSON file secure and never commit it to version control
• The private key in the .env file should include the \n characters as shown in the JSON file
• Your issuer ID must be set up in the Google Pay & Wallet Console before you can generate passes
• The BASE_URL must match your actual domain or the JWT will be rejected by Google

Usage

Start the Server

npm start

The server will start on port 3000 (or the PORT specified in .env)

API Endpoints

Generate Student Pass

POST /api/student-pass/generate

Generates a Google Wallet save URL for a student pass.

Request Body:

{
  "student": {
    "id": "12345",
    "pass_code": "STU12345ABC",
    "student_name": "John Doe"
  },
  "user": {
    "first_name": "Jane",
    "last_name": "Smith",
    "company_organization": "State University"
  }
}

Response (Success):

{
  "success": true,
  "data": {
    "walletUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiIs...",
    "message": "Student pass generated successfully"
  }
}

Response (Error):

{
  "success": false,
  "error": "Error message"
}

Health Check

GET /

Returns API information and available endpoints.

Response:

{
  "message": "Google Wallet Student Pass API",
  "version": "1.0.0",
  "endpoints": {
    "generateStudentPass": "POST /api/student-pass/generate"
  }
}

Example cURL Request

curl -X POST http://localhost:3000/api/student-pass/generate \
  -H "Content-Type: application/json" \
  -d '{
    "student": {
      "id": "12345",
      "pass_code": "STU12345ABC",
      "student_name": "John Doe"
    },
    "user": {
      "first_name": "Jane",
      "last_name": "Smith",
      "company_organization": "State University"
    }
  }'

Environment Variables

Variable	Required	Description
GOOGLE_WALLET_ISSUER_ID	Yes	Your Google Wallet issuer ID
GOOGLE_WALLET_CLIENT_EMAIL	Yes	Service account email
GOOGLE_WALLET_PRIVATE_KEY	Yes	Service account private key
BASE_URL	No	Your domain for JWT origins (default: https://yourdomain.com)
PORT	No	Server port (default: 3000)

Security Notes

• Never commit .env file to version control
• Keep your private key secure
• Use environment-specific configurations
• Rotate credentials regularly
• Add authentication middleware for production use

License

MIT