Mushu
Dashboard

Payments (mushu-pay)

Mushu Pay provides org-level billing with a prepaid wallet system. Organizations have a single wallet balance (in micro-dollars) that is shared across all apps. Usage charges are deducted from this balance.

What This Does

  • Prepaid Wallet - Organizations deposit funds, usage is charged against balance
  • Micro-Dollar Precision - Sub-cent pricing without floating-point issues (1 USD = 1,000,000 micros)
  • Stripe Integration - Checkout sessions, webhooks, and payment processing handled for you
  • No Webhook Code - We handle checkout.session.completed and deposit to wallets automatically
  • Transaction History - Full audit trail of deposits, charges, and refunds
  • Auto-Refill - Optionally auto-purchase when balance drops low

How It Works

  1. Configure Billing - Add your Stripe credentials to your organization
  2. Create Products - Define wallet packages with prices
  3. Deposit Funds - Purchase via Stripe Checkout or manual deposit
  4. Usage Charges - Services charge the wallet for usage (push notifications, media, etc.)

Quick Example

1. Check Wallet Balance

GET /orgs/{'{org_id}'}/wallet
Authorization: Bearer YOUR_TOKEN

Response:
{'{'}
  "wallet_balance": 10000000,
  "wallet_balance_usd": "$10.00"
{'}'}

2. Deposit Funds

POST /orgs/{'{org_id}'}/wallet
Authorization: Bearer YOUR_TOKEN

{'{'}
  "operation": "deposit",
  "amount_micros": 5000000,
  "description": "Manual deposit"
{'}'}

Response:
{'{'}
  "wallet_balance": 15000000,
  "wallet_balance_usd": "$15.00"
{'}'}

3. Create Checkout (for users to purchase)

POST /orgs/{'{org_id}'}/checkout
Authorization: Bearer YOUR_TOKEN

{'{'}
  "product_id": "prod_starter",
  "success_url": "https://yourapp.com/success",
  "cancel_url": "https://yourapp.com/billing"
{'}'}

Response:
{'{'}
  "checkout_url": "https://checkout.stripe.com/..."
{'}'}

Architecture

ConceptDescription
Organization The billable entity. Has a wallet balance shared across all apps.
Wallet Prepaid balance in micro-dollars. Usage charges deduct from this.
Product A wallet package. Defines price and amount deposited on purchase.
Transaction Record of a deposit, charge, or refund.

API Endpoints

EndpointPurpose
GET /orgs/:id/billing Get org billing configuration
PUT /orgs/:id/billing Update billing settings (Stripe keys, auto-refill)
GET /orgs/:id/wallet Get wallet balance
POST /orgs/:id/wallet Wallet operations (deposit, charge)
GET /orgs/:id/transactions List transaction history
POST /orgs/:id/checkout Create Stripe checkout session

Micro-Dollar Pricing

All monetary values in Mushu Pay are stored in micro-dollars for precision:

AmountMicro-dollars
$1.001,000,000
$0.0110,000
$0.0055,000
$0.0006600

This allows sub-cent pricing like $0.0006 per push notification without floating-point precision issues.

Two Billing Models

It's important to understand that Mushu Pay is for your organization's usage, not for end-user payments.

How You Pay for Mushu (Platform Billing)

Your organization pays for Mushu API usage (logins, pushes, storage, etc.) from your wallet balance. Services charge your wallet automatically:

  • Push notifications: ~$0.0006 each
  • Email notifications: ~$0.005 each
  • Media storage/transforms: Per-MB pricing

Monetizing Your App (Coming Soon)

If you want your end-users to pay you, that's a separate feature. Mushu Pay currently handles platform billing (your usage of Mushu).

Next Steps