@wopr-network/platform-core 1.14.8 → 1.16.0

package/drizzle/migrations/0004_crypto_charges.sql

@@ -0,0 +1,25 @@
+-- Replace payram_charges with crypto_charges (BTCPay Server).
+-- payram_charges existed only in the initial schema (0000) and was never used
+-- in production — no data migration is needed. The table is dropped and replaced
+-- with crypto_charges which has the same column structure but uses BTCPay-specific
+-- naming (reference_id = BTCPay invoice ID).
+--> statement-breakpoint
+DROP TABLE IF EXISTS "payram_charges";
+--> statement-breakpoint
+CREATE TABLE IF NOT EXISTS "crypto_charges" (
+	"reference_id" text PRIMARY KEY NOT NULL,
+	"tenant_id" text NOT NULL,
+	"amount_usd_cents" integer NOT NULL,
+	"status" text DEFAULT 'New' NOT NULL,
+	"currency" text,
+	"filled_amount" text,
+	"created_at" text DEFAULT (now()) NOT NULL,
+	"updated_at" text DEFAULT (now()) NOT NULL,
+	"credited_at" text
+);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_crypto_charges_tenant" ON "crypto_charges" USING btree ("tenant_id");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_crypto_charges_status" ON "crypto_charges" USING btree ("status");
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "idx_crypto_charges_created" ON "crypto_charges" USING btree ("created_at");

package/drizzle/migrations/0005_stablecoin_columns.sql

@@ -0,0 +1,7 @@
+ALTER TABLE "crypto_charges" ADD COLUMN "chain" text;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "token" text;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "deposit_address" text;--> statement-breakpoint
+ALTER TABLE "crypto_charges" ADD COLUMN "derivation_index" integer;--> statement-breakpoint
+CREATE INDEX "idx_crypto_charges_deposit_address" ON "crypto_charges" USING btree ("deposit_address");--> statement-breakpoint
+CREATE UNIQUE INDEX "uq_crypto_charges_deposit_address" ON "crypto_charges" ("deposit_address") WHERE "deposit_address" IS NOT NULL;--> statement-breakpoint
+CREATE UNIQUE INDEX "uq_crypto_charges_derivation_index" ON "crypto_charges" ("derivation_index") WHERE "derivation_index" IS NOT NULL;

package/drizzle/migrations/meta/_journal.json

@@ -29,6 +29,20 @@
       "when": 1741881600000,
       "tag": "0003_double_entry_ledger",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1741968000000,
+      "tag": "0004_crypto_charges",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1742054400000,
+      "tag": "0005_stablecoin_columns",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.14.8",
+  "version": "1.16.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -87,7 +87,6 @@
     "dockerode": ">=4",
     "drizzle-orm": ">=0.45",
     "hono": ">=4",
-    "payram": ">=1",
     "pg": ">=8",
     "resend": ">=4",
     "stripe": ">=17",
@@ -111,7 +110,6 @@
     "drizzle-orm": "^0.45.1",
     "hono": "^4.12.7",
     "lru-cache": "^11.2.6",
-    "payram": "^1.0.1",
     "pg": "^8.20.0",
     "resend": "^6.9.3",
     "stripe": "^20.4.1",
@@ -130,7 +128,10 @@
   },
   "packageManager": "pnpm@10.31.0",
   "dependencies": {
+    "@scure/base": "^2.0.0",
+    "@scure/bip32": "^2.0.1",
     "js-yaml": "^4.1.1",
+    "viem": "^2.47.4",
     "yaml": "^2.8.2"
   }
 }

package/src/account/deletion-executor-repository.ts

@@ -10,11 +10,11 @@ import {
   botInstances,
   creditBalances,
   creditTransactions,
+  cryptoCharges,
   emailNotifications,
   meterEvents,
   notificationPreferences,
   notificationQueue,
-  payramCharges,
   snapshots,
   stripeUsageReports,
   tenantCustomers,
@@ -55,7 +55,7 @@ export interface IDeletionExecutorRepository {
   listSnapshotS3Keys(tenantId: string): Promise<{ id: string; s3Key: string | null }[]>;
   deleteSnapshots(tenantId: string): Promise<number>;
   deleteBackupStatus(tenantId: string): Promise<number>;
-  deletePayramCharges(tenantId: string): Promise<number>;
+  deleteCryptoCharges(tenantId: string): Promise<number>;
   deleteTenantStatus(tenantId: string): Promise<number>;
   deleteUserRolesByUser(tenantId: string): Promise<number>;
   deleteUserRolesByTenant(tenantId: string): Promise<number>;
@@ -259,11 +259,11 @@ export class DrizzleDeletionExecutorRepository implements IDeletionExecutorRepos
     return result.length;
   }
 
-  async deletePayramCharges(tenantId: string): Promise<number> {
+  async deleteCryptoCharges(tenantId: string): Promise<number> {
     const result = await this.db
-      .delete(payramCharges)
-      .where(eq(payramCharges.tenantId, tenantId))
-      .returning({ referenceId: payramCharges.referenceId });
+      .delete(cryptoCharges)
+      .where(eq(cryptoCharges.tenantId, tenantId))
+      .returning({ referenceId: cryptoCharges.referenceId });
     return result.length;
   }
 

package/src/billing/{payram → crypto}/cents-credits-boundary.test.ts

@@ -1,20 +1,21 @@
 import { describe, expect, it } from "vitest";
+import { Credit } from "../../credits/credit.js";
 
 /**
- * Regression tests for PayRam cents/credits boundary (WOP-1058).
+ * Regression tests for crypto cents/credits boundary.
  *
  * Verifies that the USD-to-cents conversion in checkout and
  * the cents-to-credits flow in the webhook maintain correct units.
  *
  * If any of these tests fail after a rename/refactor, a _cents field was
  * incorrectly changed to store Credit raw units (nanodollars) instead of
- * USD cents. See src/monetization/credits/credit-ledger.ts for naming convention.
+ * USD cents. See src/credits/credit-ledger.ts for naming convention.
  */
-describe("WOP-1058: PayRam cents/credits boundary", () => {
-  it("USD to cents conversion is correct (mirrors checkout.ts pattern)", () => {
-    // This mirrors the conversion in payram/checkout.ts: Math.round(opts.amountUsd * 100)
+describe("Crypto cents/credits boundary", () => {
+  it("USD to cents conversion is correct (mirrors checkout.ts Credit.fromDollars pattern)", () => {
+    // This mirrors the conversion in crypto/checkout.ts: Credit.fromDollars(amountUsd).toCentsRounded()
     const amountUsd = 25;
-    const amountUsdCents = Math.round(amountUsd * 100);
+    const amountUsdCents = Credit.fromDollars(amountUsd).toCentsRounded();
     expect(amountUsdCents).toBe(2500);
     // Must NOT be nanodollar scale
     expect(amountUsdCents).toBeLessThan(1_000_000);
@@ -22,7 +23,7 @@ describe("WOP-1058: PayRam cents/credits boundary", () => {
 
   it("minimum payment amount converts to valid cents", () => {
     const MIN_PAYMENT_USD = 10;
-    const cents = Math.round(MIN_PAYMENT_USD * 100);
+    const cents = Credit.fromDollars(MIN_PAYMENT_USD).toCentsRounded();
     expect(cents).toBe(1000);
     expect(Number.isInteger(cents)).toBe(true);
     // Sanity: $10 is 1000 cents, NOT 10_000_000_000 nanodollars
@@ -30,16 +31,13 @@ describe("WOP-1058: PayRam cents/credits boundary", () => {
   });
 
   it("fractional USD amounts round correctly to cents", () => {
-    // Edge case: floating point conversion
     const amountUsd = 10.99;
-    const cents = Math.round(amountUsd * 100);
+    const cents = Credit.fromDollars(amountUsd).toCentsRounded();
     expect(cents).toBe(1099);
     expect(cents).toBeLessThan(1_000_000);
   });
 
   it("amountUsdCents stored in charge record equals USD * 100 (not nanodollars)", () => {
-    // The core invariant: payram/checkout.ts stores Math.round(amountUsd * 100)
-    // as amountUsdCents. This test proves the conversion stays at cent scale.
     const testCases: Array<{ usd: number; expectedCents: number }> = [
       { usd: 10, expectedCents: 1000 },
       { usd: 25, expectedCents: 2500 },
@@ -48,18 +46,18 @@ describe("WOP-1058: PayRam cents/credits boundary", () => {
     ];
 
     for (const { usd, expectedCents } of testCases) {
-      const amountUsdCents = Math.round(usd * 100);
+      const amountUsdCents = Credit.fromDollars(usd).toCentsRounded();
       expect(amountUsdCents).toBe(expectedCents);
       // CREDIT SCALE = 1_000_000_000. If this value approaches that, unit confusion occurred.
       expect(amountUsdCents).toBeLessThan(1_000_000);
     }
   });
 
-  it("creditedCents in webhook equals amountUsdCents from charge store (1:1 for PayRam)", () => {
-    // payram/webhook.ts: const creditCents = charge.amountUsdCents;
-    // The credited amount always equals the stored USD cents — no bonus tiers for PayRam.
+  it("creditedCents in webhook equals amountUsdCents from charge store (1:1 for crypto)", () => {
+    // crypto/webhook.ts: const creditCents = charge.amountUsdCents;
+    // The credited amount always equals the stored USD cents — no bonus tiers for crypto.
     const chargeAmountUsdCents = 2500; // $25.00
-    const creditCents = chargeAmountUsdCents; // 1:1 for PayRam
+    const creditCents = chargeAmountUsdCents; // 1:1 for crypto
     expect(creditCents).toBe(2500);
     // creditedCents must be 2500 (cents), not 25_000_000_000 (nanodollars)
     expect(creditCents).toBeLessThan(1_000_000);
@@ -68,7 +66,6 @@ describe("WOP-1058: PayRam cents/credits boundary", () => {
   it("cents-to-nanodollar scale difference is preserved as a sanity constant", () => {
     // Credit.SCALE = 1_000_000_000 nanodollars per dollar
     // 1 USD cent = 10_000_000 nanodollars (SCALE / 100)
-    // This test documents the relationship so future developers understand the gap.
     const CREDIT_SCALE = 1_000_000_000;
     const CENTS_PER_DOLLAR = 100;
     const NANODOLLARS_PER_CENT = CREDIT_SCALE / CENTS_PER_DOLLAR;

package/src/billing/crypto/charge-store.test.ts

@@ -0,0 +1,142 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { CryptoChargeRepository } from "./charge-store.js";
+
+describe("CryptoChargeRepository", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let store: CryptoChargeRepository;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+    await beginTestTransaction(pool);
+  });
+
+  afterAll(async () => {
+    await endTestTransaction(pool);
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await rollbackTestTransaction(pool);
+    store = new CryptoChargeRepository(db);
+  });
+
+  it("create() stores a charge with New status", async () => {
+    await store.create("inv-001", "tenant-1", 2500);
+
+    const charge = await store.getByReferenceId("inv-001");
+    expect(charge).not.toBeNull();
+    expect(charge?.referenceId).toBe("inv-001");
+    expect(charge?.tenantId).toBe("tenant-1");
+    expect(charge?.amountUsdCents).toBe(2500);
+    expect(charge?.status).toBe("New");
+    expect(charge?.creditedAt).toBeNull();
+  });
+
+  it("getByReferenceId() returns null when not found", async () => {
+    const charge = await store.getByReferenceId("inv-nonexistent");
+    expect(charge).toBeNull();
+  });
+
+  it("updateStatus() updates status, currency and filled_amount", async () => {
+    await store.create("inv-002", "tenant-2", 5000);
+    await store.updateStatus("inv-002", "Settled", "BTC", "0.00025");
+
+    const charge = await store.getByReferenceId("inv-002");
+    expect(charge?.status).toBe("Settled");
+    expect(charge?.currency).toBe("BTC");
+    expect(charge?.filledAmount).toBe("0.00025");
+  });
+
+  it("updateStatus() handles partial updates (no currency)", async () => {
+    await store.create("inv-003", "tenant-3", 1000);
+    await store.updateStatus("inv-003", "Processing");
+
+    const charge = await store.getByReferenceId("inv-003");
+    expect(charge?.status).toBe("Processing");
+    expect(charge?.currency).toBeNull();
+  });
+
+  it("isCredited() returns false before markCredited", async () => {
+    await store.create("inv-004", "tenant-4", 1500);
+    expect(await store.isCredited("inv-004")).toBe(false);
+  });
+
+  it("markCredited() sets creditedAt", async () => {
+    await store.create("inv-005", "tenant-5", 3000);
+    await store.markCredited("inv-005");
+
+    const charge = await store.getByReferenceId("inv-005");
+    expect(charge?.creditedAt).not.toBeNull();
+  });
+
+  it("isCredited() returns true after markCredited", async () => {
+    await store.create("inv-006", "tenant-6", 2000);
+    await store.markCredited("inv-006");
+    expect(await store.isCredited("inv-006")).toBe(true);
+  });
+
+  describe("stablecoin charges", () => {
+    it("creates a stablecoin charge with chain/token/address", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "sc:base:usdc:0x123",
+        tenantId: "tenant-1",
+        amountUsdCents: 1000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xabc123",
+        derivationIndex: 42,
+      });
+      const charge = await store.getByReferenceId("sc:base:usdc:0x123");
+      expect(charge).not.toBeNull();
+      expect(charge?.chain).toBe("base");
+      expect(charge?.token).toBe("USDC");
+      expect(charge?.depositAddress).toBe("0xabc123");
+      expect(charge?.derivationIndex).toBe(42);
+      expect(charge?.amountUsdCents).toBe(1000);
+    });
+
+    it("looks up charge by deposit address", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "sc:base:usdc:0x456",
+        tenantId: "tenant-2",
+        amountUsdCents: 5000,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xdef456",
+        derivationIndex: 43,
+      });
+      const charge = await store.getByDepositAddress("0xdef456");
+      expect(charge).not.toBeNull();
+      expect(charge?.tenantId).toBe("tenant-2");
+      expect(charge?.amountUsdCents).toBe(5000);
+    });
+
+    it("returns null for unknown deposit address", async () => {
+      const charge = await store.getByDepositAddress("0xnonexistent");
+      expect(charge).toBeNull();
+    });
+
+    it("gets next derivation index (0 when empty)", async () => {
+      const idx = await store.getNextDerivationIndex();
+      expect(idx).toBe(0);
+    });
+
+    it("gets next derivation index (max + 1)", async () => {
+      await store.createStablecoinCharge({
+        referenceId: "sc:idx-test",
+        tenantId: "t",
+        amountUsdCents: 100,
+        chain: "base",
+        token: "USDC",
+        depositAddress: "0xidxtest",
+        derivationIndex: 5,
+      });
+      const idx = await store.getNextDerivationIndex();
+      expect(idx).toBe(6);
+    });
+  });
+});

package/src/billing/crypto/charge-store.ts

@@ -0,0 +1,166 @@
+import { eq, sql } from "drizzle-orm";
+import type { PlatformDb } from "../../db/index.js";
+import { cryptoCharges } from "../../db/schema/crypto.js";
+import type { CryptoPaymentState } from "./types.js";
+
+export interface CryptoChargeRecord {
+  referenceId: string;
+  tenantId: string;
+  amountUsdCents: number;
+  status: string;
+  currency: string | null;
+  filledAmount: string | null;
+  creditedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  chain: string | null;
+  token: string | null;
+  depositAddress: string | null;
+  derivationIndex: number | null;
+}
+
+export interface StablecoinChargeInput {
+  referenceId: string;
+  tenantId: string;
+  amountUsdCents: number;
+  chain: string;
+  token: string;
+  depositAddress: string;
+  derivationIndex: number;
+}
+
+export interface ICryptoChargeRepository {
+  create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void>;
+  getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null>;
+  updateStatus(
+    referenceId: string,
+    status: CryptoPaymentState,
+    currency?: string,
+    filledAmount?: string,
+  ): Promise<void>;
+  markCredited(referenceId: string): Promise<void>;
+  isCredited(referenceId: string): Promise<boolean>;
+  createStablecoinCharge(input: StablecoinChargeInput): Promise<void>;
+  getByDepositAddress(address: string): Promise<CryptoChargeRecord | null>;
+  getNextDerivationIndex(): Promise<number>;
+}
+
+/**
+ * Manages crypto charge records in PostgreSQL.
+ *
+ * Each charge maps a BTCPay invoice ID to a tenant and tracks
+ * the payment lifecycle (New → Processing → Settled/Expired/Invalid).
+ *
+ * amountUsdCents stores the requested amount in USD cents (integer).
+ * This is NOT nanodollars — Credit.fromCents() handles the conversion
+ * when crediting the ledger in the webhook handler.
+ */
+export class DrizzleCryptoChargeRepository implements ICryptoChargeRepository {
+  constructor(private readonly db: PlatformDb) {}
+
+  /** Create a new charge record when an invoice is created. */
+  async create(referenceId: string, tenantId: string, amountUsdCents: number): Promise<void> {
+    await this.db.insert(cryptoCharges).values({
+      referenceId,
+      tenantId,
+      amountUsdCents,
+      status: "New",
+    });
+  }
+
+  /** Get a charge by reference ID. Returns null if not found. */
+  async getByReferenceId(referenceId: string): Promise<CryptoChargeRecord | null> {
+    const row = (await this.db.select().from(cryptoCharges).where(eq(cryptoCharges.referenceId, referenceId)))[0];
+    if (!row) return null;
+    return this.toRecord(row);
+  }
+
+  private toRecord(row: typeof cryptoCharges.$inferSelect): CryptoChargeRecord {
+    return {
+      referenceId: row.referenceId,
+      tenantId: row.tenantId,
+      amountUsdCents: row.amountUsdCents,
+      status: row.status,
+      currency: row.currency ?? null,
+      filledAmount: row.filledAmount ?? null,
+      creditedAt: row.creditedAt ?? null,
+      createdAt: row.createdAt,
+      updatedAt: row.updatedAt,
+      chain: row.chain ?? null,
+      token: row.token ?? null,
+      depositAddress: row.depositAddress ?? null,
+      derivationIndex: row.derivationIndex ?? null,
+    };
+  }
+
+  /** Update charge status and payment details from webhook. */
+  async updateStatus(
+    referenceId: string,
+    status: CryptoPaymentState,
+    currency?: string,
+    filledAmount?: string,
+  ): Promise<void> {
+    await this.db
+      .update(cryptoCharges)
+      .set({
+        status,
+        currency,
+        filledAmount,
+        updatedAt: sql`now()`,
+      })
+      .where(eq(cryptoCharges.referenceId, referenceId));
+  }
+
+  /** Mark a charge as credited (idempotency flag). */
+  async markCredited(referenceId: string): Promise<void> {
+    await this.db
+      .update(cryptoCharges)
+      .set({
+        creditedAt: sql`now()`,
+        updatedAt: sql`now()`,
+      })
+      .where(eq(cryptoCharges.referenceId, referenceId));
+  }
+
+  /** Check if a charge has already been credited (for idempotency). */
+  async isCredited(referenceId: string): Promise<boolean> {
+    const row = (
+      await this.db
+        .select({ creditedAt: cryptoCharges.creditedAt })
+        .from(cryptoCharges)
+        .where(eq(cryptoCharges.referenceId, referenceId))
+    )[0];
+    return row?.creditedAt != null;
+  }
+
+  /** Create a stablecoin charge with chain/token/deposit address. */
+  async createStablecoinCharge(input: StablecoinChargeInput): Promise<void> {
+    await this.db.insert(cryptoCharges).values({
+      referenceId: input.referenceId,
+      tenantId: input.tenantId,
+      amountUsdCents: input.amountUsdCents,
+      status: "New",
+      chain: input.chain,
+      token: input.token,
+      depositAddress: input.depositAddress,
+      derivationIndex: input.derivationIndex,
+    });
+  }
+
+  /** Look up a charge by its deposit address. */
+  async getByDepositAddress(address: string): Promise<CryptoChargeRecord | null> {
+    const row = (await this.db.select().from(cryptoCharges).where(eq(cryptoCharges.depositAddress, address)))[0];
+    if (!row) return null;
+    return this.toRecord(row);
+  }
+
+  /** Get the next available HD derivation index (max + 1, or 0 if empty). */
+  async getNextDerivationIndex(): Promise<number> {
+    const result = await this.db
+      .select({ maxIdx: sql<number>`coalesce(max(${cryptoCharges.derivationIndex}), -1)` })
+      .from(cryptoCharges);
+    return (result[0]?.maxIdx ?? -1) + 1;
+  }
+}
+
+export { DrizzleCryptoChargeRepository as CryptoChargeRepository };

package/src/billing/crypto/checkout.test.ts

@@ -0,0 +1,93 @@
+import type { PGlite } from "@electric-sql/pglite";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PlatformDb } from "../../db/index.js";
+import { beginTestTransaction, createTestDb, endTestTransaction, rollbackTestTransaction } from "../../test/db.js";
+import { CryptoChargeRepository } from "./charge-store.js";
+import { createCryptoCheckout, MIN_PAYMENT_USD } from "./checkout.js";
+import type { BTCPayClient } from "./client.js";
+
+function createMockClient(overrides: { createInvoice?: ReturnType<typeof vi.fn> } = {}): BTCPayClient {
+  return {
+    createInvoice:
+      overrides.createInvoice ??
+      vi.fn().mockResolvedValue({
+        id: "inv-mock-001",
+        checkoutLink: "https://btcpay.example.com/i/inv-mock-001",
+      }),
+  } as unknown as BTCPayClient;
+}
+
+describe("createCryptoCheckout", () => {
+  let pool: PGlite;
+  let db: PlatformDb;
+  let chargeStore: CryptoChargeRepository;
+  let client: BTCPayClient;
+
+  beforeAll(async () => {
+    ({ db, pool } = await createTestDb());
+    await beginTestTransaction(pool);
+  });
+
+  afterAll(async () => {
+    await endTestTransaction(pool);
+    await pool.close();
+  });
+
+  beforeEach(async () => {
+    await rollbackTestTransaction(pool);
+    chargeStore = new CryptoChargeRepository(db);
+    client = createMockClient();
+  });
+
+  it("rejects amounts below $10 minimum", async () => {
+    await expect(createCryptoCheckout(client, chargeStore, { tenant: "t-1", amountUsd: 5 })).rejects.toThrow(
+      `Minimum payment amount is $${MIN_PAYMENT_USD}`,
+    );
+  });
+
+  it("rejects amounts of exactly $0", async () => {
+    await expect(createCryptoCheckout(client, chargeStore, { tenant: "t-1", amountUsd: 0 })).rejects.toThrow();
+  });
+
+  it("calls client.createInvoice with correct params", async () => {
+    const createInvoice = vi.fn().mockResolvedValue({
+      id: "inv-abc",
+      checkoutLink: "https://btcpay.example.com/i/inv-abc",
+    });
+    const mockClient = createMockClient({ createInvoice });
+
+    await createCryptoCheckout(mockClient, chargeStore, { tenant: "t-test", amountUsd: 25 });
+
+    expect(createInvoice).toHaveBeenCalledOnce();
+    const args = createInvoice.mock.calls[0][0];
+    expect(args.amountUsd).toBe(25);
+    expect(args.buyerEmail).toContain("t-test@");
+  });
+
+  it("stores the charge with correct amountUsdCents (converts from USD)", async () => {
+    const createInvoice = vi.fn().mockResolvedValue({
+      id: "inv-store-test",
+      checkoutLink: "https://btcpay.example.com/i/inv-store-test",
+    });
+    const mockClient = createMockClient({ createInvoice });
+
+    await createCryptoCheckout(mockClient, chargeStore, { tenant: "t-2", amountUsd: 25 });
+
+    const charge = await chargeStore.getByReferenceId("inv-store-test");
+    expect(charge).not.toBeNull();
+    expect(charge?.tenantId).toBe("t-2");
+    expect(charge?.amountUsdCents).toBe(2500); // $25.00 = 2500 cents
+    expect(charge?.status).toBe("New");
+  });
+
+  it("returns referenceId and url", async () => {
+    const result = await createCryptoCheckout(client, chargeStore, { tenant: "t-3", amountUsd: 10 });
+
+    expect(result.referenceId).toBe("inv-mock-001");
+    expect(result.url).toBe("https://btcpay.example.com/i/inv-mock-001");
+  });
+
+  it("accepts exactly $10 (minimum boundary)", async () => {
+    await expect(createCryptoCheckout(client, chargeStore, { tenant: "t-4", amountUsd: 10 })).resolves.not.toBeNull();
+  });
+});

package/src/billing/crypto/checkout.ts

@@ -0,0 +1,48 @@
+import crypto from "node:crypto";
+import { Credit } from "../../credits/credit.js";
+import type { ICryptoChargeRepository } from "./charge-store.js";
+import type { BTCPayClient } from "./client.js";
+import type { CryptoCheckoutOpts } from "./types.js";
+
+/** Minimum payment amount in USD. */
+export const MIN_PAYMENT_USD = 10;
+
+/**
+ * Create a BTCPay invoice and store the charge record.
+ *
+ * Returns the BTCPay-hosted checkout page URL and invoice ID.
+ * The user is redirected to checkoutLink to complete the crypto payment.
+ *
+ * NOTE: amountUsd is converted to cents (integer) for the charge store.
+ * The charge store holds USD cents, NOT nanodollars.
+ */
+export async function createCryptoCheckout(
+  client: BTCPayClient,
+  chargeStore: ICryptoChargeRepository,
+  opts: CryptoCheckoutOpts,
+): Promise<{ referenceId: string; url: string }> {
+  if (opts.amountUsd < MIN_PAYMENT_USD) {
+    throw new Error(`Minimum payment amount is $${MIN_PAYMENT_USD}`);
+  }
+
+  const orderId = `crypto:${opts.tenant}:${crypto.randomUUID()}`;
+
+  const invoice = await client.createInvoice({
+    amountUsd: opts.amountUsd,
+    orderId,
+    buyerEmail: `${opts.tenant}@${process.env.PLATFORM_DOMAIN ?? "wopr.bot"}`,
+  });
+
+  // Store the charge record for webhook correlation.
+  // amountUsdCents = USD * 100 (cents, NOT nanodollars).
+  // Credit.fromDollars() handles the float → integer boundary safely via Math.round
+  // on the nanodollar scale, then toCentsRounded() converts back to integer cents.
+  // This avoids direct floating-point multiplication for the cents conversion.
+  const amountUsdCents = Credit.fromDollars(opts.amountUsd).toCentsRounded();
+  await chargeStore.create(invoice.id, opts.tenant, amountUsdCents);
+
+  return {
+    referenceId: invoice.id,
+    url: invoice.checkoutLink,
+  };
+}