Developer Documentation

MICROZ_API_KEY=mz_live_your_secret_key_here

curl -X POST https://api.microz.net/v1/apps \
  -H "X-API-Key: mz_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My AI App",
    "slug": "my-ai-app",
    "cogs_per_unit_microcents": 30000,
    "price_per_unit_microcents": 50000,
    "description": "GPT-4 powered writing assistant"
  }'

  Your Frontend          Your Backend           Microz API           Stripe
  ============          ============           ==========           ======
       |                      |                      |                  |
  1.   |--- Stripe.js ------->|                      |                  |
       |  (card form)         |                      |                  |
       |                      |                      |                  |
  2.   |  pm_xxx token ------>|                      |                  |
       |                      |                      |                  |
  3.   |                      |-- POST /v1/users/ -->|                  |
       |                      |    register          |--- Attach PM -->|
       |                      |                      |                  |
  4.   |                      |<-- user_id ----------|                  |
       |                      |                      |                  |
  5.   |  (user makes         |                      |                  |
       |   AI request)        |                      |                  |
       |                      |                      |                  |
  6.   |                      |-- POST /v1/charge -->|                  |
       |                      |   (ledger only,      |  (no card hit)   |
       |                      |    <50ms)            |                  |
       |                      |                      |                  |
  7.   |                      |    ... charges accumulate ...           |
       |                      |                      |                  |
  8.   |                      |                      |-- Settle ------->|
       |                      |                      |  (single charge) |
       |                      |                      |                  |
  9.   |                      |<-- webhook: ---------|                  |
       |                      |  settlement.completed|                  |

npm install @stripe/stripe-js @stripe/react-stripe-js

import { loadStripe } from '@stripe/stripe-js';

// IMPORTANT: This is Microz's publishable key, NOT your own Stripe key
export const stripePromise = loadStripe(
  'pk_test_51TIeBSAcokt2OJG3M1aNpUjjSwRoTqpLreJGwK8aIzLcTKZYtkFESWUWl6PEMvnVSHS0nXu2cmLcCU7rLCYIQoLh00s7YfLz8l'
);

import { useState } from 'react';
import {
  Elements,
  CardElement,
  useStripe,
  useElements,
} from '@stripe/react-stripe-js';
import { stripePromise } from './stripe';

function CardFormInner({ onToken }: { onToken: (pm: string) => void }) {
  const stripe = useStripe();
  const elements = useElements();
  const [error, setError] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!stripe || !elements) return;

    setLoading(true);
    setError(null);

    const card = elements.getElement(CardElement);
    if (!card) return;

    const { error: stripeError, paymentMethod } =
      await stripe.createPaymentMethod({
        type: 'card',
        card,
      });

    if (stripeError) {
      setError(stripeError.message ?? 'Card error');
      setLoading(false);
      return;
    }

    // Send pm_xxx to your backend
    onToken(paymentMethod.id);
    setLoading(false);
  };

  return (
    <form onSubmit={handleSubmit}>
      <CardElement
        options={{
          style: {
            base: {
              fontSize: '16px',
              color: '#ffffff',
              '::placeholder': { color: '#6b7280' },
            },
          },
        }}
      />
      {error && <p style={{ color: '#ef4444' }}>{error}</p>}
      <button type="submit" disabled={!stripe || loading}>
        {loading ? 'Processing...' : 'Save Card'}
      </button>
    </form>
  );
}

// Wrap with Elements provider
export function CardForm({ onToken }: { onToken: (pm: string) => void }) {
  return (
    <Elements stripe={stripePromise}>
      <CardFormInner onToken={onToken} />
    </Elements>
  );
}

async function registerUser(email: string, paymentMethodId: string) {
  const res = await fetch('/api/register', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email, payment_method_token: paymentMethodId }),
  });

  if (!res.ok) throw new Error('Registration failed');
  const { user_id } = await res.json();
  // Store user_id in your session/database
  return user_id;
}

const MICROZ_BASE = 'https://api.microz.net';
const MICROZ_API_KEY = process.env.MICROZ_API_KEY; // mz_live_...

async function microz(method: string, path: string, body?: object) {
  const res = await fetch(`${MICROZ_BASE}${path}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': MICROZ_API_KEY!,
    },
    body: body ? JSON.stringify(body) : undefined,
  });

  const data = await res.json();
  if (!res.ok) throw new MicrozError(data);
  return data;
}

class MicrozError extends Error {
  code: string;
  status: number;
  account_status?: string;

  constructor(data: any) {
    super(data.error || 'Unknown error');
    this.code = data.code;
    this.status = data.status;
    this.account_status = data.account_status;
  }
}

// In your /api/register endpoint:
const result = await microz('POST', '/v1/users/register', {
  email: 'user@example.com',
  payment_method_token: 'pm_1abc2def3ghi...',  // From Stripe.js
  display_name: 'Jane Doe',                     // Optional
});

// Response:
// {
//   "user_id": "550e8400-e29b-41d4-a716-446655440000",
//   "account_status": "active",
//   "policy_window_deadline": "2026-04-09T14:30:00Z"
// }

// Save the user_id in your database, associated with this user
await db.users.update({
  where: { email: 'user@example.com' },
  data: { microz_user_id: result.user_id },
});

import { randomUUID } from 'crypto';

async function chargeForInference(userId: string, model: string) {
  const idempotencyKey = `inf_${randomUUID()}`;

  const result = await microz('POST', '/v1/charge', {
    user_id: userId,
    app_slug: 'my-ai-app',
    units: 1,
    description: `${model} inference call`,
    idempotency_key: idempotencyKey,
  });

  // Response:
  // {
  //   "status": "queued",
  //   "charge_id": "e8b7c6d5-...",
  //   "amount_microcents": 50000,         // $0.005
  //   "balance_microcents": 2500000,      // $2.50 accumulated
  //   "next_trigger": {
  //     "type": "threshold",
  //     "remaining_microcents": 2500000   // $2.50 until settlement
  //   },
  //   "idempotency_key": "inf_abc123...",
  //   "created_at": "2026-04-03T14:30:00Z"
  // }

  return result;
}

const balance = await microz('GET', `/v1/users/${userId}/balance`);

// Response:
// {
//   "balance_microcents": 2500000,
//   "account_status": "active",
//   "policy_window_deadline": "2026-04-09T14:30:00Z",
//   "next_trigger": {
//     "type": "threshold",
//     "remaining_microcents": 2500000
//   },
//   "lifetime_charges": 15000000,
//   "lifetime_settled": 12500000,
//   "merchant_attributions": [
//     {
//       "merchant_id": "...",
//       "name": "My AI App",
//       "balance_microcents": 2500000
//     }
//   ]
// }

// Format for display
const balanceDollars = (balance.balance_microcents / 1_000_000).toFixed(2);
console.log(`Current balance: $${balanceDollars}`);

const settlement = await microz(
  'POST',
  `/v1/settlement/${userId}/settle`
);

// Response:
// {
//   "settlement_id": "f9a8b7c6-...",
//   "status": "initiated"
// }

// The actual settlement result arrives via the
// settlement.completed or settlement.failed webhook.

const result = await microz(
  'PUT',
  `/v1/users/${userId}/instrument`,
  { payment_method_token: 'pm_new_token...' }
);

// Response:
// {
//   "success": true,
//   "account_status": "active",
//   "policy_window_deadline": "2026-04-09T14:30:00Z"
// }

// Account is immediately reactivated.
// Outstanding balance will be settled on next trigger.

async function handleBillableAction(userId: string) {
  // 1. Check local subscription quota
  const user = await db.users.findUnique({ where: { id: userId } });

  if (user.remaining_quota > 0) {
    // Still within subscription - decrement locally
    await db.users.update({
      where: { id: userId },
      data: { remaining_quota: { decrement: 1 } },
    });
    return { billed: false, source: 'subscription' };
  }

  // 2. Quota exhausted - charge via Microz as overage
  const charge = await microz('POST', '/v1/charge', {
    user_id: user.microz_user_id,
    app_slug: 'my-ai-app',
    units: 1,
    description: 'GPT-4 overage',
    idempotency_key: `ovg_${randomUUID()}`,
    quota_mode: true,  // Marks this as an overage charge
  });

  return { billed: true, source: 'overage', charge };
}

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

// In your webhook handler:
app.post('/webhooks/microz', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-microz-signature'] as string;
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, process.env.MICROZ_WEBHOOK_SECRET!)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);
  // Process event...
  res.status(200).send('OK');
});

  UNREGISTERED
       |
       | POST /v1/users/register
       v
    ACTIVE  <------------------------------------------+
       |                                                |
       | (balance >= threshold OR Day 6)                |
       v                                                |
    SETTLING                                            |
       |                                                |
       +--- success -----> ACTIVE (balance reset) ------+
       |
       +--- card declined (after retries) ---> SUSPENDED_DECLINED
       |                                            |
       |                                            | PUT /instrument
       |                                            |  (new card)
       |                                            v
       |                                         ACTIVE
       |
       +--- below COGS floor ---> SUSPENDED_LOW_BALANCE
                                       |
                                       | User returns, charges accumulate,
                                       | balance exceeds floor
                                       v
                                  ACTIVE_CLEARING
                                       |
                                       | Settlement succeeds
                                       v
                                     ACTIVE

  PERMANENTLY_BANNED  (chargeback - no recovery)

async function canUserProceed(userId: string): Promise<boolean> {
  const { account_status } = await microz(
    'GET',
    `/v1/users/${userId}/balance`
  );

  switch (account_status) {
    case 'active':
    case 'active_clearing':
      return true;

    case 'suspended_declined':
      // Redirect to card update page
      throw new CardUpdateRequiredError();

    case 'suspended_low_balance':
      // The charge call itself will transition them to active_clearing
      // But you may want to show a notice
      return false;

    case 'permanently_banned':
      throw new AccountBannedError();

    default:
      return false;
  }
}

floor = processing_fees + merchant_cogs + protection_buffer

Where:
  processing_fees  = Stripe fee (2.9% + $0.30 per charge)
  merchant_cogs    = Your declared COGS for all units in this settlement
  protection_buffer = 10% of (processing_fees + merchant_cogs)

Example:
  Settlement amount: $2.00 (2,000,000 microcents)
  Stripe fee: $2.00 * 2.9% + $0.30 = $0.358
  Merchant COGS: 70 units * $0.003/unit = $0.21
  Protection buffer: ($0.358 + $0.21) * 10% = $0.057

  Floor = $0.358 + $0.21 + $0.057 = $0.625

  Since $2.00 > $0.625, settlement proceeds.

// Good: Unique per logical action
const key = `user_${userId}_action_${actionId}`;

// Good: UUID per request (safe for retries of same request)
const key = `req_${randomUUID()}`;

// Bad: Reusing keys across different logical actions
const key = 'same-key-every-time'; // DON'T DO THIS

import express from 'express';
import crypto from 'crypto';

const app = express();

// ── Config ──────────────────────────────────────────────────────
const MICROZ_BASE = 'https://api.microz.net';
const MICROZ_API_KEY = process.env.MICROZ_API_KEY!;       // mz_live_...
const WEBHOOK_SECRET = process.env.MICROZ_WEBHOOK_SECRET!;

// ── Microz client ──────────────────────────────────────────────
async function microz(method: string, path: string, body?: object) {
  const res = await fetch(`${MICROZ_BASE}${path}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': MICROZ_API_KEY,
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  const data = await res.json();
  if (!res.ok) {
    const err = new Error(data.error) as any;
    err.code = data.code;
    err.status = res.status;
    err.account_status = data.account_status;
    throw err;
  }
  return data;
}

// ── 1. Register user ───────────────────────────────────────────
app.post('/api/register', express.json(), async (req, res) => {
  try {
    const { email, payment_method_token, display_name } = req.body;

    // Register with Microz
    const result = await microz('POST', '/v1/users/register', {
      email,
      payment_method_token,
      display_name,
    });

    // Save microz_user_id in your database
    // await db.users.create({ email, microz_user_id: result.user_id });

    res.json({ user_id: result.user_id });
  } catch (err: any) {
    res.status(err.status || 500).json({ error: err.message });
  }
});

// ── 2. AI inference endpoint (charges per call) ────────────────
app.post('/api/ai/generate', express.json(), async (req, res) => {
  try {
    const { microz_user_id, prompt } = req.body;
    const idempotencyKey = `gen_${crypto.randomUUID()}`;

    // Pre-flight: check account status (optional, for better UX)
    const balance = await microz(
      'GET',
      `/v1/users/${microz_user_id}/balance`
    );

    if (balance.account_status === 'suspended_declined') {
      return res.status(402).json({
        error: 'Payment method declined. Please update your card.',
        update_card: true,
      });
    }

    if (balance.account_status === 'permanently_banned') {
      return res.status(403).json({ error: 'Account banned.' });
    }

    // ── Do the actual AI work ──
    const aiResult = await callOpenAI(prompt);

    // ── Charge for it ──
    const charge = await microz('POST', '/v1/charge', {
      user_id: microz_user_id,
      app_slug: 'my-ai-app',
      units: 1,
      description: 'GPT-4 inference',
      idempotency_key: idempotencyKey,
    });

    res.json({
      result: aiResult,
      usage: {
        charge_id: charge.charge_id,
        amount: '$' + (charge.amount_microcents / 1_000_000).toFixed(4),
        balance: '$' + (charge.balance_microcents / 1_000_000).toFixed(2),
      },
    });
  } catch (err: any) {
    if (err.code === 'ACCOUNT_SUSPENDED') {
      return res.status(402).json({
        error: 'Account suspended',
        account_status: err.account_status,
      });
    }
    res.status(500).json({ error: err.message });
  }
});

// ── 3. Card update endpoint ────────────────────────────────────
app.put('/api/update-card', express.json(), async (req, res) => {
  try {
    const { microz_user_id, payment_method_token } = req.body;

    const result = await microz(
      'PUT',
      `/v1/users/${microz_user_id}/instrument`,
      { payment_method_token }
    );

    res.json({
      success: true,
      account_status: result.account_status,
    });
  } catch (err: any) {
    res.status(err.status || 500).json({ error: err.message });
  }
});

// ── 4. Webhook handler ─────────────────────────────────────────
app.post(
  '/webhooks/microz',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    // Verify signature
    const signature = req.headers['x-microz-signature'] as string;
    const payload = req.body.toString();
    const expected = crypto
      .createHmac('sha256', WEBHOOK_SECRET)
      .update(payload, 'utf8')
      .digest('hex');

    if (
      !crypto.timingSafeEqual(
        Buffer.from(signature || '', 'hex'),
        Buffer.from(expected, 'hex')
      )
    ) {
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(payload);

    switch (event.event) {
      case 'settlement.completed':
        console.log(`Settlement ${event.settlement_id}: $${
          (event.amount_microcents / 1_000_000).toFixed(2)
        } collected from user ${event.user_id}`);
        // Send receipt email, update records
        break;

      case 'settlement.failed':
        console.log(`Settlement failed for user ${event.user_id}: ${event.failure_reason}`);
        // Flag user, show card-update prompt on next visit
        // await db.users.update({
        //   where: { microz_user_id: event.user_id },
        //   data: { needs_card_update: true },
        // });
        break;

      case 'account.suspended_low_balance':
        console.log(`User ${event.user_id} suspended (low balance)`);
        // Restrict access until they return
        break;

      case 'account.suspended_declined':
        console.log(`User ${event.user_id} card declined`);
        // Force card update on next login
        break;

      case 'account.cleared':
        console.log(`User ${event.user_id} cleared, back to active`);
        // Restore full access
        break;

      case 'chargeback.received':
        console.log(`CHARGEBACK: User ${event.user_id} permanently banned`);
        // Immediately revoke all access
        // await db.users.update({
        //   where: { microz_user_id: event.user_id },
        //   data: { banned: true, banned_reason: 'chargeback' },
        // });
        break;

      case 'threshold.approaching':
        console.log(`User ${event.user_id} at ${event.percentage}% of threshold`);
        // Optional: send usage notification
        break;
    }

    res.status(200).send('OK');
  }
);

// ── Placeholder for your AI call ───────────────────────────────
async function callOpenAI(prompt: string) {
  // Your actual OpenAI/Anthropic/etc. integration
  return { text: 'AI response here' };
}

app.listen(3000, () => console.log('Server running on :3000'));

import { useState, useEffect } from 'react';
import { CardForm } from './CardForm'; // From the Frontend Integration section

function App() {
  const [userId, setUserId] = useState<string | null>(
    localStorage.getItem('microz_user_id')
  );
  const [needsCardUpdate, setNeedsCardUpdate] = useState(false);

  // ── Registration flow ──
  async function handleCardToken(pmToken: string) {
    const res = await fetch('/api/register', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        email: 'user@example.com',
        payment_method_token: pmToken,
      }),
    });
    const { user_id } = await res.json();
    localStorage.setItem('microz_user_id', user_id);
    setUserId(user_id);
  }

  // ── Card update flow ──
  async function handleCardUpdate(pmToken: string) {
    await fetch('/api/update-card', {
      method: 'PUT',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        microz_user_id: userId,
        payment_method_token: pmToken,
      }),
    });
    setNeedsCardUpdate(false);
  }

  // ── AI generation ──
  async function generate(prompt: string) {
    const res = await fetch('/api/ai/generate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        microz_user_id: userId,
        prompt,
      }),
    });

    if (res.status === 402) {
      const data = await res.json();
      if (data.update_card) setNeedsCardUpdate(true);
      return null;
    }

    return res.json();
  }

  // ── Render ──
  if (!userId) {
    return (
      <div>
        <h2>Enter your card to get started</h2>
        <CardForm onToken={handleCardToken} />
      </div>
    );
  }

  if (needsCardUpdate) {
    return (
      <div>
        <h2>Please update your card</h2>
        <p>Your card was declined. Enter a new card to continue.</p>
        <CardForm onToken={handleCardUpdate} />
      </div>
    );
  }

  return (
    <div>
      <h2>AI Generator</h2>
      <button onClick={() => generate('Write me a poem')}>
        Generate ($0.005/call)
      </button>
    </div>
  );
}

{
  "error": "Human-readable error message",
  "code": "MACHINE_READABLE_CODE",
  "status": 400,
  "account_status": "suspended_declined"  // Present when relevant
}