Migrating from Stripe Issuing to Naive

• Cards live behind your Stripe secret key, Stripe dashboard, and Stripe’s Cardholder / Card object graph — funded from a pooled Issuing/Treasury balance you top up yourself.
• A Stripe Cardholder scopes cards and nothing else. It is a KYC entity for issuing — it has no idea about the agent’s inbox, its vault secrets, its OAuth connections, or any other KYC you ran.
• “Who let this agent issue a $5k card, and what else can this agent touch?” is answered in Stripe for cards, and in unrelated systems for everything else. There is no shared accountability.

• The tenant user that holds a card is the same user that owns its email inbox, its vault secrets, its KYC, and its connections.
• Whether an agent may issue or fund a card — and up to what total — is decided by that user’s Account Kit at execution time, not by trusting your own code to check first.
• Every cardholder create, card issue, top-up, and transaction lands in the same per-user activity log as everything else the agent does.

​

Concept map

​

Before / after: the core path

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// 1. Create the cardholder (KYC entity)
const cardholder = await stripe.issuing.cardholders.create({
  type: "individual",
  name: "John Doe",
  email: "john@acme.com",
  billing: {
    address: {
      line1: "123 Main St",
      city: "San Francisco",
      state: "CA",
      postal_code: "94105",
      country: "US",
    },
  },
});

// 2. Issue a virtual card with spending controls, funded from your Issuing balance
const card = await stripe.issuing.cards.create({
  cardholder: cardholder.id,
  type: "virtual",
  currency: "usd",
  spending_controls: {
    spending_limits: [{ amount: 10000, interval: "monthly" }], // $100/mo
  },
});

// 3. Reveal the PAN/CVC (requires PCI compliance or Stripe Elements)
const full = await stripe.issuing.cards.retrieve(card.id, {
  expand: ["number", "cvc"],
});
// full.number, full.cvc, full.exp_month, full.exp_year

import { Naive } from "@usenaive-sdk/server";

const naive = new Naive({ apiKey: process.env.NAIVE_API_KEY! });
const client = naive.forUser("user_123"); // same id space as your own users
const base = "https://api.usenaive.ai/v1/users/user_123";
const auth = { Authorization: `Bearer ${process.env.NAIVE_API_KEY}`, "Content-Type": "application/json" };

// 1. Create the cardholder for this identity (required for managed_virtual)
await fetch(`${base}/cards/cardholder`, {
  method: "POST", headers: auth,
  body: JSON.stringify({
    firstName: "John", lastName: "Doe", email: "john@acme.com",
    billingLine1: "123 Main St", billingCity: "San Francisco",
    billingState: "CA", billingPostalCode: "94105",
    dobDay: 15, dobMonth: 6, dobYear: 1990,
  }),
});

// 2. Issue a card — funded via hosted checkout, returns checkout_url
const created = await client.cards.create({
  name: "Ops Card",
  spending_limit_cents: 10000, // $100 funded cap
  provider: "managed_virtual",
});
// open created.checkout_url to fund, then issue:
await fetch(`${base}/cards/${created.card.id}/check-payment`, { method: "POST", headers: auth });

// 3. Reveal the PAN/CVC once active
const details = await (await fetch(`${base}/cards/${created.card.id}/details`, { headers: auth })).json();
// details.number, details.cvc, details.exp_month, details.exp_year

• Funding model. Stripe Issuing typically draws from a pooled Issuing/Treasury balance you top up. Naive funds each card through a hosted checkout (checkout_url) for the card’s amount, then issues it on check-payment. There is no shared balance to manage.
• Spend limits. Stripe’s spending_controls can include per-interval and per-MCC rules. Naive’s spending_limit_cents is a single funded cap per card — simpler, but not category- or interval-aware. See the gaps.
• The cardholder is your identity, not a standalone KYC object. In Stripe a Cardholder exists only for issuing. In Naive the cardholder hangs off a tenant user that also owns the agent’s inbox, vault, connections, and KYC.

​

Funding and issuing

// You pre-fund your Issuing balance (Treasury / top-ups) out of band;
// the card is spendable as soon as it is created and your balance covers it.
const card = await stripe.issuing.cards.create({
  cardholder: "ich_123", type: "virtual", currency: "usd",
  spending_controls: { spending_limits: [{ amount: 50000, interval: "monthly" }] },
});

// Each card is funded by its own checkout; top-up later the same way.
const created = await client.cards.create({ name: "Ads", spending_limit_cents: 50000, provider: "managed_virtual" });
// → created.checkout_url  (fund it), then:
//   POST /v1/users/{id}/cards/{cardId}/check-payment  → status: "active"
//   POST /v1/users/{id}/cards/{cardId}/top-up { amount_cents }  → another checkout_url

• On Naive, issuing a card, creating a cardholder, and topping up are sensitive and may be approval-gated by the Account Kit — the call can return 202 { status: "pending_approval", approval_id } until a human approves, then the API replays it.
• A card’s status moves pending_payment → active after check-payment confirms funding. See Card statuses.

​

Minimal viable migration

npm install @usenaive-sdk/server

​

Consolidate further once you’re on Naive

// One cardholder per customer; isolates cards, and only cards.
const ch = await stripe.issuing.cardholders.create({ type: "individual", name: "Acme Bot", billing });
await stripe.issuing.cards.create({ cardholder: ch.id, type: "virtual", currency: "usd" });

// The inbox, the secrets, the OAuth grants, the KYC for this customer's agent
// live in entirely separate systems with their own tenancy.

import { isPendingApproval } from "@usenaive-sdk/server";

// One tenant user per customer; isolates *every* primitive.
const acme = await naive.users.create({ external_id: dbCustomer.id, email: dbCustomer.email });
const client = naive.forUser(acme.id);

// Same identity owns the card…
const card = await client.cards.create({ name: "Ops", spending_limit_cents: 25000, provider: "managed_virtual" });
if (isPendingApproval(card)) { /* surface card.approval_id to a human */ }

// …and the inbox, the secrets, the connections, the KYC — one handle.
const inbox = await client.email.createInbox({ local_part: "billing" });
await client.vault.put("internal.api_key", "key_xyz");
await client.connections.connect("quickbooks", { callbackUrl });

​

Gain #1 — one identity across primitives

• With Stripe Issuing, the agent’s cards are an island. With Naive, naive.forUser(acme.id) is a single handle to cards and email and vault and connections and KYC.
• You provision a customer’s whole agent footprint from one identity, and tear it down from one place. Sibling tenants can never read each other’s cards, secrets, or inboxes.

​

Gain #2 — execution-time permission enforcement

• Whether an agent may issue or fund a card is policy on the Account Kit — not a check you hand-write, and not “we trust the agent to call the right function.”

const starter = await naive.accountKits.create({
  name: "Starter",
  primitives_config: {
    cards: { enabled: true, requiresApproval: true }, // issuing/top-up freezes for a human
    email: { enabled: true },
    vault: { enabled: true },
  },
});
await naive.accountKits.assignUser(starter.id, acme.id);

• The agent’s code is identical for every tier — client.cards.create({ … }). Whether the call runs is decided by the caller’s kit at execution time:
  • primitives_config.cards.enabled: false → the exact same line returns forbidden, no code change.
  • requiresApproval: true → issuing, cardholder creation, and top-ups freeze as a pending approval; the API replays them only after a human approves.
  • The funded spending_limit_cents caps how much was loaded onto the card — spend is generally bounded by that funded amount, though treat issuer/network behavior as authoritative for edge cases.
• Stripe gates who has Issuing access at the Connect-account level and per-authorization via your own webhook logic. Naive additionally gates the issuance and funding decision per tenant user, declaratively, with no per-swipe handler to run. (Per-authorization MCC control is still a Stripe strength — see gaps.)

​

Gain #3 — unified accountability

• Every cardholder create, card issue, top-up, and transaction for a customer lands in one per-user activity log — alongside their email, vault, and connection events, not in a separate Stripe dashboard:

const { events } = await naive.forUser(acme.id).logs.query({ limit: 50 });
// "what did this agent spend, and what else did it do?" — cards, email, secrets, one timeline

• That is the question that is hard to answer when cards live in Stripe, email lives in another vendor, and secrets live somewhere else. Under Naive it is a single query.

​

What does not map yet

​

Where to go next

• /cards primitive — full cardholder/issue/fund/transaction lifecycle
• Cards API reference — exact request/response shapes
• cards SDK sub-client — typed method signatures
• Account Kits and Approvals — the policy model that makes execution-time issuance governance real
• Tenant users — the identity that the consolidation hangs off

​

Related reading (blog)

• Why consolidate agent infra on one governed identity — migration thesis behind this guide
• Building AI Agents Into Your SaaS — tenant user anchor for every migration
• Spend Caps Approvals Revocation For Ai Agents — card spend caps and approval gates