Credits System

​

Overview

​

How Credits Work

• 1 Credit = 1 Feature Use (approximately)
• Credits are deducted when you use paid features
• Balance is tracked in real-time
• Transactions are logged for full transparency
• Monthly allocations based on your tier

​

Getting Credits

​

New User Bonus

​

Monthly Allocations

• Your balance is reset to your monthly allocation amount
• Unused credits do not roll over to the next month
• Purchased credits are tracked separately in lifetime stats

​

Purchasing Credits

• PayGate (Cryptocurrency: USDC on Polygon)
• Telegram Stars (in-app payments)
• Thirdweb (Web3 payments)

​

Earning Credits

• Refer a friend: +10 credits for you
• New user gets: +25 bonus credits
• No limit on referrals (subject to rate limiting)

• Claim free credits daily by logging in
• Bonus amount varies by tier
• Check status at GET /api/user/daily-bonus/status
• Claim bonus at POST /api/user/daily-bonus/claim

​

Feature Pricing

​

Current Pricing (March 2026)

​

Legacy Features (Disabled)

• Session Play (Legacy) - 25 credits per session (replaced by per-slide billing)
• Manual Session Create (Legacy) - 30 credits (now unified with session_create)
• Import JOIP (Legacy) - 20 credits (now unified with session_create)
• AI Undress (Legacy Alias) - 25 credits (replaced by low/high quality options)

​

Credit Balance

​

Checking Your Balance

import { useAuth } from '@/lib/AuthContext';

function MyComponent() {
  const { user } = useAuth();
  
  if (user?.credits) {
    const { balance, tier, isLowBalance, nextAllocationDate } = user.credits;
    
    return (
      <div>
        <p>Balance: {balance} credits</p>
        <p>Tier: {tier}</p>
        {isLowBalance && <Warning>Low balance!</Warning>}
        <p>Next allocation: {new Date(nextAllocationDate).toLocaleDateString()}</p>
      </div>
    );
  }
}

GET /api/auth/user

Response:
{
  "id": "user123",
  "email": "[email protected]",
  "credits": {
    "balance": 150,
    "tier": "free",
    "isLowBalance": false,
    "nextAllocationDate": "2026-04-01T00:00:00.000Z"
  }
}

​

Low Balance Warning

// Low balance threshold check
const threshold = 20; // Default
const isLowBalance = balance < threshold;

​

Transaction History

​

Viewing Transactions

interface CreditTransaction {
  id: number;
  userId: string;
  amount: number;              // Positive = credit, Negative = debit
  balanceAfter: number;        // Balance after this transaction
  type: 'purchase' | 'allocation' | 'usage' | 'refund' | 'admin_grant' | 'bonus';
  feature?: string;            // Which feature was used (for 'usage' type)
  description: string;         // Human-readable description
  relatedEntityType?: string;  // 'session', 'media', etc.
  relatedEntityId?: string;    // ID of related entity
  metadata?: object;           // Additional transaction data
  createdAt: timestamp;
}

​

Transaction Types

​

API Endpoints

{
  "balance": 150,
  "tier": "free",
  "nextAllocationDate": "2026-04-01T00:00:00.000Z",
  "isLowBalance": false
}

{
  "transactions": [
    {
      "id": 123,
      "amount": -10,
      "balanceAfter": 140,
      "type": "usage",
      "feature": "smart_caption",
      "description": "Used Smart Caption",
      "createdAt": "2026-03-02T10:30:00.000Z"
    }
  ],
  "hasMore": true,
  "total": 45
}

{
  "totalSpent": 350,
  "mostUsedFeatures": [
    {
      "feature": "smart_caption",
      "count": 15,
      "totalCredits": 150
    },
    {
      "feature": "session_create",
      "count": 4,
      "totalCredits": 100
    }
  ]
}

[
  {
    "featureKey": "smart_caption",
    "displayName": "Smart Caption",
    "creditsRequired": 10,
    "isPremiumOnly": false,
    "description": "Generate AI caption for an image"
  }
]

​

Credit Mechanics

​

Deduction Process

1. Feature Request
   • User initiates feature (e.g., generate caption)
   • System identifies feature key (e.g., smart_caption)
2. Atomic Check & Deduct
   • Database transaction with row-level locking
   • Prevents race conditions from concurrent requests
   • Either succeeds completely or fails (no partial deductions)
3. Transaction Logging
   • Records amount, feature, balance after
   • Logs related entity (e.g., which session/media)
   • Timestamps for audit trail

// Atomic check and deduct in a single transaction
const result = await creditService.checkAndDeductCredits(
  userId,
  'smart_caption',
  {
    relatedEntityType: 'media',
    relatedEntityId: mediaId,
    description: 'Generated caption for uploaded image'
  }
);

if (!result.success) {
  if (result.error === 'insufficient_credits') {
    return res.status(402).json({
      error: 'Insufficient credits',
      required: result.required,
      current: result.current
    });
  }
  // Handle other errors...
}

// Success: proceed with feature

​

Refund Process

1. Automatic Refund
   • System detects failure (error during AI generation, etc.)
   • Credits are automatically returned
   • Refund transaction logged
2. Example:
   // AI Undress generation failed
   await creditService.addCredits(
     userId,
     45, // Refund amount
     'refund',
     'AI Undress generation failed - refunded',
     {
       originalTransactionId: txId,
       reason: 'generation_timeout'
     }
   );
   

​

Race Condition Prevention

-- Lock user's credit row during transaction
SELECT * FROM user_credits
WHERE user_id = $1
FOR UPDATE;

-- Check balance
IF balance >= required THEN
  -- Deduct credits
  UPDATE user_credits
  SET balance = balance - required,
      lifetime_used = lifetime_used + required
  WHERE user_id = $1;
  
  -- Log transaction
  INSERT INTO credit_transactions (...) VALUES (...);
  
  COMMIT;
ELSE
  ROLLBACK;
END IF;

• No double-charging even with concurrent requests
• Balance always consistent
• Transaction history always accurate

​

Tier System

​

Available Tiers

​

Tier Management

• Contact admin to change tiers
• Changes take effect on next allocation cycle
• Current balance preserved during tier change

POST /api/admin/users/:userId/tier

Request:
{
  "tier": "full_access"
}

Response:
{
  "userId": "user123",
  "tier": "full_access",
  "monthlyAllocation": 2500,
  "balance": 150 // Preserved
}

​

Credit Packages

​

Purchasing Flow

1. Select Package
   • View available packages at /credits/purchase
   • Choose payment method (PayGate, Telegram Stars, Thirdweb)
2. Payment Session
   • System creates payment session in database
   • Generates unique payment ID
   • Sets expiration (typically 1 hour)
3. Payment Processing
   • User completes payment via provider
   • Provider sends callback to server
   • Server validates payment authenticity
4. Credit Delivery
   • Upon successful payment verification:
   • Credits added to account
   • Transaction logged as type purchase
   • Payment session marked as completed

​

Payment Session Structure

interface PaymentSession {
  id: string;                    // UUID v4
  userId: string;
  packageId: number;
  creditsAmount: number;         // Credits to be delivered
  priceUsd: number;              // Price in cents
  paymentMethod: 'paygate' | 'telegram' | 'thirdweb';
  status: 'pending' | 'completed' | 'failed' | 'expired' | 'refunded';
  
  // PayGate-specific
  addressIn?: string;            // Encrypted payment address
  polygonAddressIn?: string;     // Decrypted address (for callback matching)
  coinType?: string;             // e.g., "polygon_usdc"
  txnIdIn?: string;              // Provider → order wallet
  txnIdOut?: string;             // Order wallet → merchant
  
  // Telegram-specific
  telegramPaymentId?: string;    // Telegram charge ID
  telegramExpectedStars?: number;// Stars price locked at creation
  
  // Thirdweb-specific
  thirdwebPaymentId?: string;
  thirdwebTransactionHash?: string;
  
  createdAt: timestamp;
  expiresAt: timestamp;
  callbackReceivedAt?: timestamp;
}

​

Callback Security

1. PayGate:
   • Validates polygonAddressIn matches session
   • Checks callbackSecretHash if provided
   • Verifies transaction amounts
2. Telegram:
   • Validates Telegram charge ID
   • Verifies user ID matches session
   • Checks Stars amount matches expected
3. Thirdweb:
   • Validates payment ID
   • Verifies blockchain transaction hash
   • Checks transaction confirmation

​

Admin Features

​

Manual Credit Grants

POST /api/admin/credits/grant

Request:
{
  "userId": "user123",
  "amount": 100,
  "reason": "Compensation for bug report"
}

Response:
{
  "success": true,
  "newBalance": 250,
  "transactionId": 456
}

​

Feature Pricing Management

PATCH /api/admin/credits/pricing/:featureKey

Request:
{
  "creditsRequired": 15,
  "description": "Updated description"
}

POST /api/admin/credits/pricing

Request:
{
  "featureKey": "new_feature",
  "displayName": "New Feature",
  "creditsRequired": 20,
  "description": "Description here",
  "isPremiumOnly": false
}

​

Tier Configuration

PATCH /api/admin/credits/tiers/:tierKey

Request:
{
  "monthlyCredits": 3000,
  "displayName": "Updated Name"
}

​

Troubleshooting

{
  "error": "Insufficient credits",
  "required": 25,
  "current": 10
}

GET /api/credits/transactions?page=1&limit=10
# Look for 'refund' type transaction

SELECT * FROM payment_sessions
WHERE id = 'payment-session-uuid';

​

Best Practices

​

For Users

1. Monitor Your Balance
   • Keep an eye on credit balance before starting expensive operations
   • Enable low balance warnings
2. Use Free Features First
   • Test with manual sessions (no caption generation)
   • Use existing community content
   • Experiment before committing credits
3. Plan Monthly Usage
   • Remember: credits don’t roll over
   • Use your allocation before it resets
   • Consider upgrading tier if consistently running out
4. Refer Friends
   • Easiest way to earn extra credits
   • Both you and your friend benefit
   • No limit on referrals

​

For Developers

1. Always use checkAndDeductCredits()
   // Good: Atomic operation
   const result = await creditService.checkAndDeductCredits(
     userId, 'feature_key', metadata
   );
   
   // Bad: Race condition possible
   const hasEnough = await creditService.hasEnoughCredits(userId, 'feature_key');
   if (hasEnough) {
     await creditService.deductCredits(userId, amount, 'feature_key');
   }
   
2. Implement Refunds
   try {
     const result = await expensiveOperation();
   } catch (error) {
     // Refund on failure
     await creditService.addCredits(
       userId, amount, 'refund',
       'Operation failed - refunded'
     );
     throw error;
   }
   
3. Log Meaningful Descriptions
   await creditService.checkAndDeductCredits(
     userId,
     'smart_caption',
     {
       relatedEntityType: 'media',
       relatedEntityId: media.id,
       description: `Smart caption for ${media.fileName}` // Specific!
     }
   );
   
4. Handle All Error Cases
   if (result.error === 'insufficient_credits') {
     return res.status(402).json({ error: 'Insufficient credits', ... });
   }
   if (result.error === 'premium_only') {
     return res.status(403).json({ error: 'Premium feature', ... });
   }
   if (result.error === 'not_found') {
     return res.status(404).json({ error: 'Feature not found', ... });
   }
   

​

Related Documentation

• Authentication - User accounts and login
• Referral Program - Earn credits by referring friends
• Profile Management - View credit stats in your profile