WalletPass.ai

Appearance

API Reference ​

Complete API documentation for all WalletPass.ai endpoints.

Base URLs ​

  • Local Development: https://generate.walletpass.ai (Pass Generation)
  • Tenant Manager: https://tenant.walletpass.ai
  • Member Data: https://member.walletpass.ai
  • Notification Service: https://notification.walletpass.ai

Authentication ​

Most endpoints require API key authentication via the X-API-Key header:

http
X-API-Key: wp_your_api_key_here

API keys are generated when creating a tenant and have the format: wp_ followed by a secure random string.

Pass Generation Service ​

Health Check ​

GET /health

Check if the service is running.

Example:

bash
curl https://generate.walletpass.ai/health

Response:

json
{
  "status": "success",
  "message": "Pass Generation Service is healthy",
  "service": "pass-generation-service",
  "timestamp": "2025-01-09T10:30:00Z"
}

Demo Pass Generation ​

GET /demo

Generate a demo Apple Wallet pass without authentication.

Query Parameters:

ParameterTypeDefaultDescription
pointsstring"156"Number of loyalty points
levelstring"Gold"Membership level
memberIdstring"12345678"Member ID
stripstring"strip.png"Strip image filename

Example:

bash
# Basic demo pass
curl -O https://generate.walletpass.ai/demo

# Customized demo pass
curl -O "https://generate.walletpass.ai/demo?points=500&level=Silver&memberId=John123"

Response: Binary .pkpass file

Create Pass from Member ​

POST /v1/passes/create-from-member

Create a wallet pass from existing member data.

Headers:

http
Content-Type: application/json
X-API-Key: wp_your_api_key_here

Request Body:

json
{
  "member_id": "MEMBER-001",
  "pass_type": "apple",
  "company_name": "My Company",
  "pass_style_id": "optional-style-uuid"
}

Parameters:

  • member_id (required): Member identifier
  • pass_type (required): "apple" or "google"
  • company_name (required): Company/brand name
  • pass_style_id (optional): UUID of pass style to use
  • style_group_id (optional): UUID of style group (for dynamic styling)
  • external_id (optional, Google only): External ID for Google Wallet

Example - Apple Pass:

bash
curl -X POST https://generate.walletpass.ai/v1/passes/create-from-member \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -d '{
    "member_id": "MEMBER-001",
    "pass_type": "apple",
    "company_name": "My Company"
  }'

Example - Google Pass:

bash
curl -X POST https://generate.walletpass.ai/v1/passes/create-from-member \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -d '{
    "member_id": "MEMBER-001",
    "pass_type": "google",
    "company_name": "My Company",
    "external_id": "EXT-MEMBER-001"
  }'

Response:

json
{
  "status": "success",
  "message": "Pass created successfully",
  "data": {
    "pass_id": "550e8400-e29b-41d4-a716-446655440000",
    "member_id": "MEMBER-001",
    "pass_type": "apple",
    "pass_url": "https://pay.google.com/gp/v/save/...",
    "created_at": "2025-01-09T10:30:00Z",
    "download_url": "/v1/passes/550e8400-e29b-41d4-a716-446655440000/download"
  }
}

Download Pass ​

GET /v1/passes/{pass_id}/download

Download a previously created pass file.

Headers:

http
X-API-Key: wp_your_api_key_here

Example:

bash
curl -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -O https://generate.walletpass.ai/v1/passes/550e8400-e29b-41d4-a716-446655440000/download

Response: Binary .pkpass file (Apple) or redirect to Google Wallet URL

Create Pass Style ​

POST /v1/pass-styles

Create a custom pass style for branding.

Headers:

http
Content-Type: application/json
X-API-Key: wp_your_api_key_here

Request Body:

json
{
  "name": "Default Orange",
  "is_default": true,
  "brand_colors": {
    "foreground_color": "rgb(255,255,255)",
    "background_color": "rgb(255, 107, 53)",
    "label_color": "rgb(255,255,255)"
  },
  "assets": {
    "apple": {
      "logo": "logo.png",
      "strip": "strip.png"
    },
    "google": {
      "logo": "logo.png",
      "hero": "hero.png"
    }
  },
  "barcode": {
    "format": "PKBarcodeFormatQR"
  },
  "primary_fields": [
    {
      "key": "tier",
      "label": "Membership",
      "value": "{tier}"
    }
  ],
  "back_fields": [
    {
      "key": "website",
      "label": "Website",
      "value": "https://walletpass.ai"
    }
  ]
}

Example:

bash
curl -X POST https://generate.walletpass.ai/v1/pass-styles \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -d '{
    "name": "Premium Style",
    "is_default": false,
    "brand_colors": {
      "foreground_color": "#FFFFFF",
      "background_color": "#FF6B35",
      "label_color": "#FFFFFF"
    },
    "barcode": {
      "format": "PKBarcodeFormatQR"
    }
  }'

Response:

json
{
  "status": "success",
  "data": {
    "id": "uuid-here",
    "name": "Premium Style",
    "is_default": false,
    "created_at": "2025-01-09T10:30:00Z"
  }
}

List Pass Styles ​

GET /v1/pass-styles

Get all pass styles for the tenant.

Headers:

http
X-API-Key: wp_your_api_key_here

Example:

bash
curl -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  https://generate.walletpass.ai/v1/pass-styles

Create Style Group ​

POST /v1/style-groups

Create a style group for dynamic styling based on points.

Headers:

http
Content-Type: application/json
X-API-Key: wp_your_api_key_here

Request Body:

json
{
  "name": "Loyalty Tier Colors",
  "rules": [
    {
      "pass_style_id": "style-uuid-1",
      "min_points": 0,
      "max_points": 100
    },
    {
      "pass_style_id": "style-uuid-2",
      "min_points": 101,
      "max_points": 200
    }
  ]
}

Example:

bash
curl -X POST https://generate.walletpass.ai/v1/style-groups \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -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": 0
      }
    ]
  }'

Member Data Service ​

Register Member ​

POST /v1/members/register

Register a new loyalty program member.

Headers:

http
Content-Type: application/json
X-API-Key: wp_your_api_key_here

Request Body:

json
{
  "member_id": "MEMBER-001",
  "member_name": "John Doe",
  "member_email": "john@example.com",
  "phone_number": "+1234567890",
  "style_group_id": "optional-style-group-uuid"
}

Example:

bash
curl -X POST https://member.walletpass.ai/v1/members/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -d '{
    "member_id": "MEMBER-001",
    "member_name": "John Doe",
    "member_email": "john@example.com",
    "phone_number": "+1234567890"
  }'

Response:

json
{
  "status": "success",
  "data": {
    "id": "member-uuid",
    "member_id": "MEMBER-001",
    "member_name": "John Doe",
    "member_email": "john@example.com",
    "points": 0,
    "tier": "bronze",
    "created_at": "2025-01-09T10:30:00Z"
  }
}

Get Member ​

GET /v1/members/{member_id}

Get member information including all associated passes.

Headers:

http
X-API-Key: wp_your_api_key_here

Example:

bash
curl -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  https://member.walletpass.ai/v1/members/MEMBER-001

Response:

json
{
  "status": "success",
  "data": {
    "id": "member-uuid",
    "member_id": "MEMBER-001",
    "member_name": "John Doe",
    "member_email": "john@example.com",
    "points": 150,
    "tier": "silver",
    "passes": [
      {
        "pass_id": "pass-uuid-1",
        "pass_type": "apple",
        "created_at": "2025-01-09T10:30:00Z"
      },
      {
        "pass_id": "pass-uuid-2",
        "pass_type": "google",
        "pass_url": "https://pay.google.com/...",
        "created_at": "2025-01-09T10:30:00Z"
      }
    ]
  }
}

Update Member Points ​

PUT /v1/members/{member_id}/points

Update member points with operations: add, subtract, or set.

Headers:

http
Content-Type: application/json
X-API-Key: wp_your_api_key_here

Request Body:

json
{
  "points": 25,
  "operation": "add",
  "description": "Purchase bonus"
}

Operations:

  • add: Increases current balance by points
  • subtract: Decreases current balance by points (never below 0)
  • set: Overwrites current balance with points

Example - Add Points:

bash
curl -X PUT https://member.walletpass.ai/v1/members/MEMBER-001/points \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -d '{
    "points": 25,
    "operation": "add",
    "description": "Purchase bonus"
  }'

Example - Redeem Points:

bash
curl -X PUT https://member.walletpass.ai/v1/members/MEMBER-001/points \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -d '{
    "points": 10,
    "operation": "subtract",
    "description": "Reward redeem"
  }'

Response:

json
{
  "status": "success",
  "data": {
    "member_id": "MEMBER-001",
    "points": 115,
    "tier": "silver",
    "operation": "add",
    "description": "Purchase bonus"
  }
}

Create Membership Program ​

POST /v1/memberships

Define membership tiers for automatic tier assignment.

Headers:

http
Content-Type: application/json
X-API-Key: wp_your_api_key_here

Request Body:

json
{
  "name": "Loyalty Program",
  "tiers": [
    {
      "tier_name": "bronze",
      "min_points": 0,
      "max_points": 100
    },
    {
      "tier_name": "silver",
      "min_points": 101,
      "max_points": 200
    },
    {
      "tier_name": "gold",
      "min_points": 201,
      "max_points": 0
    }
  ]
}

Example:

bash
curl -X POST https://member.walletpass.ai/v1/memberships \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -d '{
    "name": "Loyalty Program",
    "tiers": [
      {
        "tier_name": "bronze",
        "min_points": 0,
        "max_points": 100
      },
      {
        "tier_name": "silver",
        "min_points": 101,
        "max_points": 200
      }
    ]
  }'

Tenant Management Service ​

Bootstrap Super Admin ​

POST /v1/bootstrap/super-admin

Create the first super admin (one-time setup).

Headers:

http
Content-Type: application/json

Request Body:

json
{
  "email": "admin@walletpass.ai",
  "password": "SecurePassword123!",
  "name": "Super Admin"
}

Example:

bash
curl -X POST https://tenant.walletpass.ai/v1/bootstrap/super-admin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@walletpass.ai",
    "password": "SecurePassword123!",
    "name": "Super Admin"
  }'

Create Bearer Token ​

POST /v1/bearer-tokens

Create a bearer token for tenant creation.

Headers:

http
Authorization: Bearer admin@walletpass.ai
Content-Type: application/json

Request Body:

json
{
  "name": "Development Token",
  "expires_at": "2026-12-31T23:59:59Z"
}

Example:

bash
curl -X POST https://tenant.walletpass.ai/v1/bearer-tokens \
  -H "Authorization: Bearer admin@walletpass.ai" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Development Token",
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Onboard Tenant ​

POST /v1/onboard

Create a new tenant with isolated resources.

Headers:

http
Authorization: Bearer bt_your_bearer_token_here
Content-Type: application/json

Request Body:

json
{
  "company_name": "My Company",
  "contact_email": "contact@mycompany.com",
  "contact_name": "John Doe"
}

Example:

bash
curl -X POST https://tenant.walletpass.ai/v1/onboard \
  -H "Authorization: Bearer bt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "My Company",
    "contact_email": "contact@mycompany.com",
    "contact_name": "John Doe"
  }'

Response:

json
{
  "status": "success",
  "message": "Tenant onboarded successfully",
  "data": {
    "tenant_id": "tenant-uuid",
    "api_key": "wp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "company_name": "My Company",
    "created_at": "2025-01-09T10:30:00Z"
  }
}

Distribution Service ​

Send Pass via SMS ​

POST /v1/distribution/send-pass-sms

Send a pass to a member via SMS with short link.

Headers:

http
Content-Type: application/json
X-API-Key: wp_your_api_key_here

Query Parameters:

  • dry_run=1 - Test without sending actual SMS

Request Body (by pass_id):

json
{
  "pass_id": "pass-uuid",
  "phone_number": "+1234567890"
}

Request Body (by member_id):

json
{
  "member_id": "MEMBER-001",
  "phone_number": "+1234567890"
}

Example:

bash
curl -X POST 'https://generate.walletpass.ai/v1/distribution/send-pass-sms?dry_run=1' \
  -H "Content-Type: application/json" \
  -H "X-API-Key: wp_864e820cbbabce90ead1bc429eec64ed" \
  -d '{
    "member_id": "MEMBER-001",
    "phone_number": "+1234567890"
  }'

Error Responses ​

All error responses follow this format:

json
{
  "status": "error",
  "message": "Human-readable error message",
  "errors": [
    {
      "field": "field_name",
      "message": "Specific field error message"
    }
  ],
  "timestamp": "2025-01-09T10:30:00Z"
}

Common HTTP Status Codes ​

  • 200 OK - Request successful
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request data
  • 401 Unauthorized - API key required
  • 403 Forbidden - Invalid API key
  • 404 Not Found - Resource not found
  • 409 Conflict - Resource already exists
  • 500 Internal Server Error - Server error

WalletPass.ai Documentation

Copyright © 2024 WalletPass.ai