Organization Billing

Mushu Pay provides org-level billing with a prepaid wallet system. Each organization has a single wallet balance (in micro-dollars) that is shared across all apps.

Key Concepts

• Wallet Balance - Stored in micro-dollars (1 USD = 1,000,000 micros)
• Org-Level - One wallet per organization, shared across all apps
• Transparent Pricing - All charges shown in real dollar amounts
• Products - Define wallet packages for users to purchase

Prerequisites

Before setting up billing, you need:

1. Stripe Account - Sign up at stripe.com
2. Stripe Secret Key - From your Stripe Dashboard → Developers → API keys
3. Mushu Organization - Create one if you haven't

Setting Up Org Billing

Dashboard

1. Go to Billing in the dashboard
2. Your org's billing config is created automatically
3. Add Stripe credentials in settings

API

POST /orgs/{'{org_id}'}/billing
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{'{'}
  "stripe_secret_key": "sk_test_..."
{'}'}

Free Tier Amount

You can grant free wallet balance to new organizations automatically. Set free_tier_amount (in micro-dollars):

PUT /orgs/{'{org_id}'}/billing
{'{'}
  "free_tier_amount": 10000000
{'}'}

New organizations will automatically receive $10.00 (10,000,000 micros) when created. This appears as a "Free tier grant" transaction in their history.

Wallet Operations

Check Balance

GET /orgs/{'{org_id}'}/wallet

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

Deposit Funds

POST /orgs/{'{org_id}'}/wallet
{'{'}
  "operation": "deposit",
  "amount_micros": 5000000,
  "description": "Manual deposit"
{'}'}

Charge Wallet

POST /orgs/{'{org_id}'}/wallet
{'{'}
  "operation": "charge",
  "amount_micros": 5000,
  "description": "Push notification",
  "app_id": "app_abc123"
{'}'}

Webhook Setup

For automatic wallet deposits after purchases, set up a Stripe webhook:

1. Go to Stripe Dashboard → Developers → Webhooks
2. Click "Add endpoint"
3. Enter the URL: https://pay.mushucorp.com/webhooks/stripe
4. Select events: checkout.session.completed
5. Copy the signing secret
6. Update your billing config with the webhook secret

Auto-Refill

Configure automatic wallet top-up when balance drops below a threshold:

PUT /orgs/{'{org_id}'}/billing
{'{'}
  "auto_refill_enabled": true,
  "auto_refill_threshold": 5000000,
  "auto_refill_product_id": "prod_abc123"
{'}'}

When wallet balance drops below $5.00 (5,000,000 micros), the specified product will be automatically purchased using the saved payment method.

Micro-Dollar Pricing

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

Amount	Micro-dollars
$1.00	1,000,000
$0.01	10,000
$0.005	5,000
$0.0006	600

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

FAQ

Why micro-dollars?

Using integers (micro-dollars) instead of floating-point avoids precision issues and allows sub-cent pricing. 1 million micros = $1.00.

Test vs Live mode?

Use sk_test_... keys for testing, sk_live_... for production. Products created in test mode won't appear in live mode (Stripe limitation).

What happens to my Stripe data?

Mushu creates Products and Prices in your Stripe account. Checkout sessions and customers are also created in your account. You retain full access and ownership of all Stripe data.