API Reference

This document describes all available REST API endpoints for the Wallet Service.

Base URL: http(s)://{HOST}:{PORT} (default: http://localhost:3000)

Interactive Documentation

Access the interactive Swagger UI at /docs to explore and test the API directly in your browser.

---

Pass Management Endpoints

Update Pass

Triggers an update for a specific pass by serial number.

GET /passes/update/:serialNumber?type={apple|google}

Parameter	Type	Location	Description
serialNumber	string	path	The unique pass serial number
type	string	query	Pass type: apple or google

Response Codes:

• 200 - Pass updated successfully
• 404 - Pass not found
• 500 - Internal server error

Example:

curl "http://localhost:3000/passes/update/abc123?type=apple"

---

Send Pass via Email

Sends digital membership passes to a member via email.

GET /passes/send?salesforceId={id}&type={apple|google}&key={apiKey}

Parameter	Type	Location	Description
salesforceId	string	query	Salesforce account ID
type	string	query	Pass type: apple or google
key	string	query	API authentication key
appartmentId	string	query	(Optional) Filter by department ID

Response Codes:

• 200 - Email sent successfully
• 401 - Unauthorized (invalid key)
• 404 - Member not found
• 500 - Internal server error

Example:

curl "http://localhost:3000/passes/send?salesforceId=0011X00000wF1itQAC&key=YOUR_API_KEY&type=apple"

---

Apple Wallet Endpoints

These endpoints implement the Apple PassKit Web Service specification.

Get Pass by Serial Number

Retrieves the latest version of a pass.

GET /apple/v1/passes/:passTypeIdentifier/:serialNumber

Parameter	Type	Location	Description
passTypeIdentifier	string	path	Your Pass Type ID (e.g., pass.de.dotSource.DigitalMembershipCard)
serialNumber	string	path	Unique pass serial number

Headers:

Header	Required	Description
Authorization	Yes	ApplePass {authToken} or WalletPass {authToken}
If-Modified-Since	No	Timestamp to check for updates

Response:

• 200 - Returns .pkpass file
• 304 - Pass not modified
• 401 - Unauthorized
• 400 - Bad request

---

Register Device

Registers a device to receive push notifications for pass updates.

POST /apple/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber

Parameter	Type	Location	Description
deviceLibraryIdentifier	string	path	Unique device identifier
passTypeIdentifier	string	path	Your Pass Type ID
serialNumber	string	path	Pass serial number

Headers:

Header	Required	Description
Authorization	Yes	ApplePass {authToken}

Body:

{
  "pushToken": "device-push-token-string"
}

Response Codes:

• 200 - Already registered
• 201 - Successfully registered
• 401 - Unauthorized

---

Unregister Device

Removes a device registration when a pass is removed from the wallet.

DELETE /apple/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber

Headers:

Header	Required	Description
Authorization	Yes	ApplePass {authToken}

Response Codes:

• 200 - Successfully unregistered
• 401 - Unauthorized

---

Get Serial Numbers for Device

Returns serial numbers of passes registered to a device.

GET /apple/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier

Parameter	Type	Location	Description
passesUpdatedSince	number	query	(Optional) Unix timestamp filter

Response:

{
  "lastUpdated": "1706889600",
  "serialNumbers": ["serial1", "serial2"]
}

Response Codes:

• 200 - Returns serial numbers
• 204 - No passes registered
• 401 - Unauthorized

---

Log Endpoint

Receives error logs from Apple Wallet.

POST /apple/v1/log

Body:

{
  "logs": ["log message 1", "log message 2"]
}

Response Codes:

• 200 - Logs received

---

Google Wallet Endpoints

Notification Callback

Receives callback notifications from Google Wallet for pass lifecycle events.

POST /google/notify

This endpoint verifies signed messages from Google using ECDSA-SHA256 and handles:

• Pass save events
• Pass delete events
• Pass update events

Security: Messages are verified using Google's public keys to ensure authenticity.

Response Codes:

• 200 - Notification processed
• 400 - Invalid message or signature

---

Authentication

Apple Wallet

Apple Wallet endpoints require an Authorization header:

Authorization: ApplePass {authToken}

or

Authorization: WalletPass {authToken}

The auth token must match the AUTH_TOKEN environment variable configured on the server.

API Key Authentication

The /passes/send endpoint requires a key query parameter for authentication.

---

Response Format

All endpoints return JSON responses with the following structure:

Success:

{
  "code": 200,
  "message": "OK"
}

Error:

{
  "code": 404,
  "message": "Not Found"
}

---

Rate Limiting

In production mode, the API enforces rate limiting:

• Max requests: 100 per 2 seconds
• Whitelisted: localhost and configured hosts

---

CORS

Cross-Origin Resource Sharing is enabled for all origins with the following methods:

• GET
• POST
• DELETE
• HEAD

Allowed headers: Content-Type, Authorization, Accept