HIP-0018: Payment Processing Standard

Abstract

This proposal defines the payment processing standard for the Hanzo ecosystem. Hanzo Commerce is the billing, subscription, and payment service that bridges the native Hanzo PSP (Hanzo Pay — the same payment engine white-labeled as lux-pay on Lux and per-brand elsewhere) with the internal credit system managed by Hanzo IAM (HIP-26). Card data is tokenized inside the Hanzo Vault PCI CDE; on-chain rails settle $AI directly. Every dollar a user pays is converted into credits. Every AI inference, API call, or compute job consumes credits. Commerce handles the money side; IAM holds the balance; the LLM Gateway (HIP-4) and Cloud services meter usage.

No external-processor dependency. First-party Hanzo/Lux/Zoo/Zen surfaces process payments through the native PSP, never through a third-party processor that can deplatform us. Commerce keeps a pluggable provider-adapter interface so a brand MAY add a regional rail, but no first-party flow depends on one.

The system is designed around a single invariant: IAM is the source of truth for user balances. Commerce writes credits in; Cloud and Gateway write credits out. No service other than IAM may directly mutate a user's balance. All mutations flow through IAM's transaction API.

Repository: github.com/hanzoai/commerce Port: 8090 (COMMERCE_HTTP) Docker: ghcr.io/hanzoai/commerce:latest

Motivation

The Problem

AI usage billing is fundamentally different from SaaS billing. A typical SaaS charges a flat monthly fee for feature access. AI platforms charge per token, per image, per minute of audio, per GPU-second of fine-tuning. The unit costs span four orders of magnitude -- a GPT-3.5 completion might cost $0.0002 while a GPT-4 Vision request with a large image costs $0.30. Presenting these raw costs to users is confusing and creates billing anxiety.

Meanwhile, the Hanzo ecosystem has multiple services that incur costs:

1. LLM Gateway (HIP-4): Chat completions, embeddings, image generation across 100+ providers
2. Cloud: Hosted model inference, fine-tuning jobs, compute clusters
3. MCP Tools: Computer use, browser automation, search -- each with different cost profiles
4. Agent SDK: Multi-agent orchestration where a single user request may trigger dozens of LLM calls

Without a unified billing system, each service would need its own payment integration, balance tracking, and invoice generation. Users would face multiple bills, multiple balances, and no single view of their spend.

Why This Matters

1. User trust: Users must understand what they are paying for. Opaque per-token billing erodes trust. Credits provide a simple, predictable unit.
2. Service isolation: LLM Gateway should not need payment-processor credentials. It should check a balance, do the work, and report usage. Payment processing is not its job.
3. Fraud prevention: A single source of truth for balances prevents double-spending. If Cloud and Gateway each maintained independent balances, a race condition could allow a user to spend more than they have.
4. Regulatory compliance: Financial transactions require audit trails, PCI compliance, and dispute resolution. Centralizing this in Commerce means one team handles compliance, not five.

Design Philosophy

This section explains the why behind each major design decision. Payment systems are among the most consequential infrastructure choices a company makes. Mistakes are expensive -- literally.

Why Credits-Based Billing

AI usage is unpredictable. A user might send one message that triggers a 4-token response or one that triggers a 4,000-token response with tool calls, image generation, and web search. Showing users a per-request cost breakdown like "$0.000847 for 423 input tokens at $0.002/1K + $0.000612 for 204 output tokens at $0.003/1K" is hostile UX.

Credits provide a simple mental model: you buy credits, you spend credits. 1 credit = $0.001 USD. A $20 top-up gives you 20,000 credits. A typical GPT-4 conversation costs 50-200 credits. Users can reason about their spending without understanding tokenization, provider pricing tiers, or markup calculations.

Credits also decouple the billing unit from provider pricing. When OpenAI changes their per-token rates (which happens quarterly), we adjust the internal credit-to-token conversion without changing the user-facing credit price. The user's mental model remains stable.

The alternative -- real-time per-token billing in USD -- requires sub-cent transaction tracking, creates rounding errors that accumulate, and produces invoices with thousands of line items. Credits eliminate all three problems.

Why a Native PSP (Hanzo Pay)

Hanzo originally bridged an external processor. That dependency proved fatal: a third-party processor can deplatform an entire ecosystem at will — freezing funds, disabling checkout, and cutting off every brand that rides on it, with no recourse and no portability. This is not hypothetical; it is exactly what happened, and it is why this standard now mandates a native PSP. Payment sovereignty — owning the rail end-to-end — is a first-class requirement, not an optimization.

The native PSP (Hanzo Pay, the same engine white-labeled as lux-pay / per-brand) provides:

• Sovereignty: No external party can disable, freeze, or deplatform a first-party flow. The rail is ours; outages and policy changes are ours to manage.
• PCI offload, in-house: Card data never touches Commerce or any app server. The Hanzo Vault CDE (a dedicated PCI-DSS-scoped tokenization service) holds the card-handling surface; everything else operates on opaque tokens, keeping the broad system out of PCI scope exactly as an external processor would — but under our control.
• Hosted checkout: A native hosted payment page (served from the Vault/PSP boundary) so app servers only ever receive a signed completion webhook.
• Subscription management: Recurring billing, proration, dunning (failed-payment retry), and lifecycle hooks.
• Invoicing: Invoice generation, PDF rendering, and email delivery.
• Fraud detection: Risk scoring on the native rail; on-chain rails are inherently irreversible (no chargeback exposure).
• Marketplace payouts: Connect-style transfers for agent revenue (HIP-25) settle natively, including on-chain $AI to any wallet.

The compliance burden the standard once cited as a reason to outsource (PCI DSS: 300+ controls across 12 categories) is met by scoping the CDE to Hanzo Vault alone, not by handing the customer relationship to a party that can revoke it.

Pluggable Provider Adapters (Optional, Per-Brand)

Commerce keeps a provider-adapter interface so a brand MAY plug an additional rail (regional cards, bank transfer, a Merchant-of-Record for EU VAT, etc.). These are optional, per-brand, and never on a first-party critical path — the native PSP is always the default and the only rail a first-party surface is required to support. Adapters are registered explicitly; none is implicit or default. (Notably, no first-party surface registers an external processor that can deplatform the ecosystem.)

Why Not Blockchain-Only Payments

The Hanzo ecosystem includes $AI token (HIP-1) and on-chain settlement (HIP-25). Why not use blockchain for all payments?

1. Friction: Most developers do not have crypto wallets. Requiring wallet setup, token purchase, and gas fees for a $20 credit top-up would eliminate 90%+ of potential users.
2. Volatility: Token prices fluctuate. If a user buys credits with $AI at $0.50 and the price drops to $0.30 before they use the credits, who absorbs the loss?
3. Speed: The native PSP processes a card payment in 2-3 seconds. On-chain settlement takes 2-15 seconds depending on the chain and requires block confirmations for finality.
4. Chargebacks: Card users have dispute rights. Blockchain transactions are irreversible. Offering only crypto payments forfeits consumer protection, which is a regulatory risk.

The correct approach is both: the native PSP for fiat, blockchain for crypto. Commerce accepts both and normalizes them into credits. The user does not need to know or care which payment rail was used.

Why IAM Holds Balances

Every authenticated API call already hits IAM to validate the JWT. The LLM Gateway (HIP-4) receives a request, extracts the bearer token, and validates it against IAM's public key or calls /v1/iam/get-account. This round-trip is unavoidable -- you must authenticate before executing.

If balance lived in Commerce, every LLM call would require two round-trips:

Request -> Gateway -> IAM (auth: 3ms) -> Commerce (balance: 5ms) -> Upstream (inference: 200ms)

By storing balance in IAM, the auth check and balance check collapse into one operation:

Request -> Gateway -> IAM (auth + balance: 3ms) -> Upstream (inference: 200ms)

At 1,000 requests/second, eliminating the Commerce round-trip saves 5,000ms of cumulative latency per second and removes Commerce as a critical-path dependency. If Commerce goes down, users cannot buy credits, but they can still use existing credits because IAM is independent.

The tradeoff: balance is denormalized. Commerce is the authoritative ledger ("what transactions occurred"), and IAM is the balance cache ("what is the current balance"). A reconciliation job detects and corrects drift between the two. This is covered in detail in HIP-26 Section "Why Credit Balances Live in IAM."

Why Webhook-Driven Architecture

Payment processing is inherently asynchronous. A user clicks "Pay" on the native hosted checkout page, enters their card, waits for 3D Secure, and the PSP processes the charge. This takes 5-30 seconds. Holding a synchronous HTTP connection open for this duration is fragile.

Instead, Commerce uses webhooks:

1. Commerce creates a native PSP checkout session and returns the URL to the client.
2. Client redirects to the native hosted checkout page (served from the Vault/PSP boundary; card data never reaches Commerce).
3. User completes payment on the PCI-scoped CDE.
4. The PSP sends a signed checkout.session.completed webhook to Commerce.
5. Commerce verifies the webhook signature, records the transaction, then calls IAM to add credits.

This decouples payment processing from service delivery. If Commerce is briefly unavailable when the webhook fires, the PSP retries with exponential backoff for up to 72 hours. Eventual consistency is acceptable for billing -- a 30-second delay between payment and credit delivery is imperceptible to users.

Specification

Architecture

                              +------------------------+
                              |  Hanzo Pay (native PSP)|
                              |  + Hanzo Vault (PCI    |
                              |   CDE: card tokens)    |
                              |  Checkout/Billing/Hooks|
                              +------+------+----------+
                                     |      |
                           webhooks  |      |  checkout sessions
                                     |      |
                              +------v------v----------+
                              |    Hanzo Commerce      |
                              |    (payment logic)     |
                              |      :4242             |
                              +------+--------+--------+
                                     |        |
                      +--------------+--------+-------------+
                      |              |                      |
               add-balance    add-transaction          get-account
                      |              |                      |
                      v              v                      v
               +----------------------------------------------+
               |           Hanzo IAM (HIP-26)                 |
               |     (user balances, transactions)            |
               |            hanzo.id :8000                    |
               +----------------------------------------------+
                      ^              ^
                      |              |
               token validation  debit transactions
                      |              |
         +------------+-+     +------+----------+
         |  LLM Gateway |     |   Hanzo Cloud   |
         |   (HIP-4)    |     |  (compute jobs) |
         |    :4000      |     |                 |
         +--------------+     +-----------------+

Credit System

Credit Definition

Credits are stored as a USD-denominated float in IAM (1,000 credits = $1.00 balance). The "credit" is a user-facing abstraction; the IAM balance field stores the dollar equivalent. This means 20,000 credits = $20.00 balance.

Credit Pricing Tiers

Bulk purchases receive volume discounts:

AI Usage Credit Costs

Credit costs are derived from provider pricing plus a margin. The LLM Gateway publishes a rate card:

These rates are stored in the LLM Gateway configuration and updated when provider pricing changes. Commerce does not need to know the rates; it only processes the debit transactions that Gateway and Cloud submit to IAM.

Subscription Tiers

tiers:
  free:
    name: "Free"
    price_monthly: 0
    credits_monthly: 1000
    psp_price_id: null
    overage: blocked
    features:
      - "1,000 credits/month (~100 GPT-4 messages)"
      - "Community support"
      - "3 requests/minute rate limit"
      - "Standard models only"

  pro:
    name: "Pro"
    price_monthly: 20
    credits_monthly: 50000
    psp_price_id: "price_pro_monthly"
    overage: pay_as_you_go
    features:
      - "50,000 credits/month (~5,000 GPT-4 messages)"
      - "Priority support"
      - "60 requests/minute rate limit"
      - "All models including Premium tier"
      - "MCP tool access"
      - "Usage analytics dashboard"

  team:
    name: "Team"
    price_monthly: 100
    credits_monthly: 150000
    psp_price_id: "price_team_monthly"
    overage: pay_as_you_go
    features:
      - "150,000 credits/month"
      - "5 team members included ($15/additional)"
      - "Shared org billing"
      - "120 requests/minute rate limit"
      - "Admin dashboard"
      - "SSO via IAM (HIP-26)"

  enterprise:
    name: "Enterprise"
    price_monthly: custom
    credits_monthly: custom
    psp_price_id: "price_enterprise_custom"
    overage: invoice
    features:
      - "Custom credit allocation"
      - "Unlimited team members"
      - "Dedicated support and SLA"
      - "Custom rate limits"
      - "Volume discounts (25%+)"
      - "Invoice billing (NET 30)"
      - "SOC 2 compliance reports"

Free-tier credits reset monthly and do not accumulate. Paid-tier included credits roll over for 90 days. Purchased credits (one-time top-ups) never expire.

Subscription Lifecycle

• Upgrade: Commerce creates a PSP subscription -> the PSP charges monthly -> webhook invoice.paid -> Commerce credits IAM with included credits.
• Renewal: the PSP auto-charges -> webhook invoice.paid -> Commerce adds monthly credits. Unused credits from previous months roll over for 90 days.
• Overage: When a Pro/Team user exceeds included credits, usage continues at the standard rate. Overage is metered via PSP usage records and billed at period end alongside the subscription fee.
• Downgrade: Commerce cancels the PSP subscription at period end. Remaining credits are usable until expiry. After the period ends, the user reverts to Free tier (1,000 credits/month, hard cap).
• Payment failure: the PSP retries 3 times over 7 days using smart retries. After 3 failures the subscription enters past_due. After 14 days past_due, the subscription is canceled and the user is downgraded to Free.

Payment Flow

One-Time Credit Purchase (Fiat)

1. Client: POST /v1/billing/checkout { amount: 2000, currency: "usd", credits: 21000 }
2. Commerce creates a PSP checkout session with metadata (user_id, org_id, credits, idempotency_key)
3. Commerce returns checkout URL -> client redirects user to the native hosted checkout
4. User completes payment on the native hosted checkout page (Hanzo Vault CDE)
5. PSP fires webhook: checkout.session.completed
6. Commerce verifies webhook signature (HMAC-SHA256)
7. Commerce checks the idempotency key in the shared KV (prevent double-processing)
8. Commerce records the transaction in its OWN ledger — it does not write a
   balance into IAM. IAM's balance fields are read-only mirrors of this ledger
   (HIP-0026 §The balance mirror); the `add-balance` and `add-transaction` verbs
   an earlier revision called here do not exist and would be forbidden if they
   did (HIP-0111 §4.8).
9. The mirror follows from the ledger. A surface that gates spend reads the
   authoritative position, never the mirror.
10. User's IAM balance updated. Credits available immediately.

Crypto Payment Flow ($AI Token)

Commerce also accepts $AI token (HIP-1) payments on Hanzo Network (chain ID 36963). The user sends tokens to a per-user deposit address. Commerce's on-chain listener detects the Transfer event (1 block confirmation for <$1K, 6 for >=$1K), converts $AI to USD at the 10-minute TWAP oracle rate via HMM (HIP-8), and credits the user's IAM balance through the same add-balance/add-transaction flow as fiat.

Billing API Endpoints

Response Examples

GET /v1/billing/balance returns the user's current credit state:

{
  "balance": 15420, "balance_usd": 15.42, "tier": "pro",
  "credits_included": 50000, "credits_used": 34580, "credits_remaining": 15420,
  "period_start": "2026-02-01T00:00:00Z", "period_end": "2026-03-01T00:00:00Z",
  "auto_recharge": { "enabled": true, "threshold": 1000, "amount": 20000 }
}

GET /v1/billing/transactions returns paginated transaction history. Each transaction includes id, timestamp, category (Purchase/Recharge), credits (negative for debits), balance_after, and metadata with model/token/provider details.

GET /v1/billing/usage?period=2026-02 returns usage aggregated by model (gpt-4-turbo, claude-3-sonnet, etc.), by service (llm-gateway, cloud, mcp), and optionally by day when granularity=daily is specified.

Webhook Handling

Commerce receives webhooks from the native PSP for all payment-related events. The webhook handler follows a strict pipeline:

async def handle_psp_webhook(request):
    # 1. Verify signature (CRITICAL - prevents forgery)
    payload = request.body
    signature = request.headers["X-Webhook-Signature"]
    try:
        event = psp.verify_event(
            payload, signature, psp_webhook_secret
        )
    except psp.SignatureError:
        return Response(status=400, body="Invalid signature")

    # 2. Check idempotency (prevent double-processing)
    event_id = event["id"]
    if await kv.exists(f"webhook:processed:{event_id}"):
        return Response(status=200, body="Already processed")

    # 3. Route by event type
    handlers = {
        "checkout.session.completed": handle_checkout_completed,
        "invoice.paid": handle_invoice_paid,
        "invoice.payment_failed": handle_payment_failed,
        "customer.subscription.updated": handle_subscription_updated,
        "customer.subscription.deleted": handle_subscription_deleted,
        "charge.dispute.created": handle_dispute_created,
        "charge.refunded": handle_refund,
    }
    handler = handlers.get(event["type"])
    if handler:
        await handler(event)

    # 4. Mark as processed (72h TTL matching the PSP retry window)
    await kv.set(f"webhook:processed:{event_id}", "1", ex=259200)

    return Response(status=200)

Handled Webhook Events

Usage Metering

The LLM Gateway and Cloud services do not interact with Commerce directly for debits. They submit usage to IAM via the transaction API:

LLM Gateway receives request
    |
    +-- 1. Validate JWT (IAM)
    +-- 2. Check balance from JWT claims or /v1/iam/get-account
    +-- 3. If insufficient balance: return 402 Payment Required
    +-- 4. Execute LLM request (provider API)
    +-- 5. Calculate cost:
    |      input_tokens * input_rate + output_tokens * output_rate
    |      -> convert to USD -> round to credits
    +-- 6. Submit debit transaction to IAM:
    |      POST /v1/iam/add-transaction
    |      {
    |        "category": "Purchase",
    |        "user": "<user>",
    |        "amount": -0.012,    // negative = debit
    |        "detail": "gpt-4-turbo: 847 in + 400 out tokens"
    |      }
    +-- 7. Return response to user

The Gateway batches transaction submissions. Rather than calling IAM for every request, it accumulates usage per user over a 10-second window and submits a single aggregated transaction. This reduces IAM load by ~90% during high-throughput periods.

metering:
  batch_interval: 10s
  batch_max_size: 100
  minimum_charge: 0.001       # 1 credit minimum debit
  balance_check: jwt_claims   # or "api_call"
  insufficient_balance_code: 402
  retry_on_iam_failure: true
  retry_max_attempts: 3
  retry_backoff: exponential

Multi-Organization Billing

Each organization in IAM has independent billing. A user who belongs to multiple organizations (e.g., [email protected] is a member of both hanzo and zoo) has a separate balance in each organization context.

Organization: hanzo
  User: z
    Balance: $150.00
    Tier: Enterprise
    Transactions: [org-scoped]

Organization: zoo
  User: z
    Balance: $25.00
    Tier: Pro
    Transactions: [org-scoped]

When the LLM Gateway processes a request, the organization context is determined by the OAuth application that issued the token. A token from app-cloud (organization: hanzo) bills against the hanzo org balance. A token from app-zoo bills against the zoo org balance.

Organizations can choose between two billing modes:

• Shared pool (default for Team/Enterprise): One org-level balance. All members draw from the shared pool. The org owner manages top-ups and subscriptions.
• Individual allocation: Org admin allocates credits to each member. Members cannot exceed their allocation without admin approval.

Refund and Dispute Handling

Refund Policy

• Unused credits: Full refund within 14 days of purchase.
• Partially used credits: Pro-rated refund for unused portion within 14 days.
• After 14 days: No refund for credit purchases.
• Subscriptions: Cancel anytime; no refund for current period; access continues until period end.

Refund Flow

1. User requests refund via support or /v1/billing/refund.
2. Commerce validates eligibility (14-day window, sufficient credit balance).
3. Commerce creates a refund via the PSP (psp.refunds.create) for the original payment intent.
4. The PSP processes the refund (3-5 business days to card).
5. On webhook charge.refunded, Commerce debits the refunded credits from IAM via add-transaction with negative amount.
6. If the user's balance goes negative after the debit, the account is flagged and usage is suspended until the balance is positive.

Dispute (Chargeback) Flow

1. The PSP receives a chargeback from the card issuer -> webhook charge.dispute.created.
2. Commerce immediately freezes the user account (suspended=true in IAM), debits the disputed amount, creates a support ticket, and notifies the admin team.
3. Commerce submits evidence to the PSP: usage logs, IP addresses, login timestamps, and ToS acceptance.
4. The card network arbitrates (60-90 days). On charge.dispute.closed: if won, Commerce unfreezes the account and restores the debited amount; if lost, the account remains suspended until the balance is positive.

Invoice Generation

Commerce generates monthly invoices for all users with non-zero activity. Each invoice includes:

• Header: Hanzo AI Inc., 548 Market St, Suite 45000, San Francisco, CA 94104
• Line items: Subscription fee, credit purchases, overage charges
• Usage summary: Credits consumed by service (LLM Gateway, Cloud, MCP) with request counts
• Balance: Opening balance, credits added, usage consumed, closing balance
• Payment: Method used (card ending, wire reference, or $AI tx hash)

Invoices are stored as PDFs in MinIO (HIP-32) and emailed to the user. Enterprise customers on Net-30 receive invoices with payment instructions instead of automatic billing.

Auto-Recharge

Users can configure automatic credit purchases when their balance drops below a threshold:

POST /v1/billing/auto-recharge
Authorization: Bearer <access_token>

{
  "enabled": true,
  "threshold": 1000,
  "amount": 20000,
  "max_monthly": 5,
  "payment_method": "pm_..."
}

When the metering pipeline detects a balance crossing below the threshold, it enqueues an auto-recharge job. The job creates a PSP payment intent using the stored (tokenized) payment method, processes the charge, and credits the balance without user interaction. Auto-recharge is rate-limited (max 5/month by default) to prevent runaway charges from buggy clients or compromised API keys.

Implementation Roadmap

Phase 1: Core Billing (Completed)

• Native PSP checkout integration for one-time credit purchases
• Webhook handler for checkout.session.completed
• IAM balance update via /v1/iam/add-balance
• Transaction recording via /v1/iam/add-transaction
• Balance and transaction query endpoints
• Idempotency key tracking in the shared KV

Phase 2: Subscriptions (Completed)

• Native PSP subscription creation for Pro/Team tiers
• Monthly credit allocation on invoice.paid
• Subscription upgrade/downgrade with proration
• Dunning (failed payment) handling
• Subscription cancellation flow

Phase 3: Usage Metering (In Progress)

• LLM Gateway batched transaction submission
• Per-model credit cost configuration
• Real-time usage dashboard
• Usage breakdown by model, service, and time period
• Overage billing via PSP metered usage

Phase 4: Multi-Org and Enterprise (Planned)

• Org-level billing with shared pool mode
• Individual credit allocation per member
• Enterprise invoice billing (NET 30)
• Custom rate cards for enterprise customers
• SOC 2 Type II audit trail exports

Phase 5: Crypto Payments (Planned)

• $AI token payment acceptance on Hanzo Network
• USDC/USDT acceptance via Lux Bridge (HIP-101)
• On-chain settlement receipts
• Token-to-credit conversion via HMM oracle (HIP-8)

Security Considerations

PCI DSS Compliance

Commerce achieves PCI compliance by never handling cardholder data. Cardholder data is confined to the Hanzo Vault CDE — the only PCI-DSS-scoped component — which hosts the payment form (native hosted checkout) and issues opaque tokens. Commerce and every app server operate on tokens only; they never see, store, process, or transmit card numbers, CVVs, or expiration dates. Commerce qualifies as a SAQ A surface; the Vault carries the full SAQ D / RoC scope, isolated from the rest of the ecosystem.

Webhook Signature Verification

Every native-PSP webhook is verified using HMAC-SHA256:

# The PSP signs webhooks with the webhook signing secret (held in KMS).
# The signature includes a timestamp to prevent replay attacks.
signature = request.headers["X-Webhook-Signature"]
# Format: t=<timestamp>,v1=<signature>

expected = hmac_sha256(
    key=psp_webhook_secret,   # from KMS, never plaintext
    message=f"{timestamp}.{payload}"
)

# Reject if:
# 1. Signature does not match (forged webhook)
# 2. Timestamp is > 300 seconds old (replay attack)
# 3. Event ID already processed (duplicate delivery)

Idempotency

Every payment operation uses idempotency keys to prevent double-charging:

1. PSP Checkout: The idempotency_key in session metadata ensures retried webhooks do not create duplicate credits.
2. IAM Transactions: The transaction name field (txn_psp_{event_id}) acts as a unique constraint. IAM rejects duplicate transaction names.
3. Deduplication store: Processed webhook event IDs are persisted with a 72-hour TTL matching the PSP's retry window.

These three layers provide defense-in-depth against double-processing.

Rate Limiting

Rate limiting is enforced with sliding-window counters in the shared KV (HIP-0144). Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Audit Trail

Every financial event produces an immutable audit record:

{
  "event_id": "evt_audit_001",
  "timestamp": "2026-02-23T10:30:15.123Z",
  "action": "credit_purchase",
  "actor": {
    "user_id": "hanzo/z",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0..."
  },
  "details": {
    "psp_event_id": "evt_...",
    "psp_session_id": "cs_...",
    "amount_usd": 20.00,
    "credits_added": 21000,
    "balance_before": 5000,
    "balance_after": 26000,
    "idempotency_key": "ik_abc123"
  },
  "integrity": "sha256:ab3f..."
}

Audit records are append-only (never updated or deleted), integrity-protected with SHA-256 hash chains, retained for 7 years (financial regulatory minimum), and exportable for SOC 2 and compliance audits.

Fraud Prevention

• Velocity checks: Commerce flags users who make >5 purchases in 1 hour or >$500 in 24 hours for manual review.
• Chargeback response: Disputes trigger immediate account freeze and balance debit. Evidence is automatically compiled from usage logs.
• Free-tier abuse: Free-tier credit resets are tied to verified email addresses. Multiple accounts with the same email or phone are detected and consolidated.

Insufficient Balance Handling

When a user's balance reaches zero during an API request:

1. The LLM Gateway returns 402 Payment Required with a link to the billing page.
2. Streaming responses are terminated gracefully -- partial completions are delivered with a final chunk indicating billing exhaustion.
3. If auto-recharge is enabled, it triggers immediately, and the request can be retried.

References

1. HIP-1: $AI Token - Native currency for crypto payments
2. HIP-4: LLM Gateway - Primary usage metering source
3. HIP-8: HMM (Hanzo Market Maker) - Token price oracle for crypto-to-credit conversion
4. HIP-25: Bot Agent Wallet & RPC Billing Protocol - Agent-level billing built on Commerce
5. HIP-26: Identity & Access Management Standard - Balance storage and transaction ledger
6. HIP-27: Secrets Management Standard - KMS for PSP keys and secrets
7. HIP-1060: Pubsub — The Tenant Endpoint on the Bus - billing event distribution
8. HIP-1165: S3 — Buckets and Objects - invoice PDF storage
9. HIP-101: Hanzo-Lux Bridge Protocol - Cross-chain payment acceptance
10. Hanzo Pay (native PSP) — github.com/lux-pay (white-labeled lux-pay on Lux)
11. Hanzo Vault — PCI CDE / card tokenization
12. PCI DSS v4.0 — SAQ A / SAQ D scoping
13. PCI DSS Quick Reference Guide
14. Hanzo Commerce Repository

Copyright

Copyright and related rights waived via CC0.

Conformance status

Measured against hanzoai/commerce at c17a4f786 on 2026-09-09. The credit model ships; the payment-sovereignty claim in the abstract does not.

The native PSP does not exist as a rail. payment/processor defines sixteen ProcessorType values. The fiat ones are stripe, square, paypal, adyen, braintree, recurly, lemonsqueezy — every one a third-party processor. The first-party ones are crypto (mpc, bitcoin, ethereum, solanapay, circle) plus wire. There is no hanzopay or lux-pay type, so "the native PSP is always the default and the only rail a first-party surface is required to support" describes a rail that is not implemented.

A first-party surface's fiat default is Square. DefaultConfig() sets ProcessorPriority to Square first, annotated in the source as // fiat default — pay.hanzo.ai (Square + crypto). Stripe is registered but held un-selectable for new charges through DisabledProcessors, which is a deliberate and well-built deny policy — but it is a policy about which third-party processor is used, not evidence of a native one. The abstract's "no first-party surface registers an external processor that can deplatform the ecosystem" is contradicted by the shipped default.

This is the gap that keeps this HIP a Draft, and it is a substantive one: the document mandates payment sovereignty as a first-class requirement and gives the deplatforming history as the reason. Either the native PSP lands and the default moves to it, or this HIP is rewritten to describe Square-first fiat with crypto as the sovereign rail. It should not be marked Final while it reads as though the first has already happened.

The crypto half is sound: DefaultCryptoProcessor defaults to MPC, a first-party rail, and crypto routing is by currency rather than preference order.