Primary and Ephemeral Cards — Downcity Payments

Each user has one permanent Primary Card and at most 100 unexpired Ephemeral Cards with a positive balance. expires_at must be ISO 8601 and is stored as UTC.

const card = await bureau.credits.cards.create_ephemeral({
  user_id: "user_123",
  name: "7-day welcome credits",
  initial_credits: 1_000_000,
  expires_at: "2026-08-03T00:00:00.000Z",
  source: "welcome",
  ref: "campaign_v1",
  idempotency_key: "welcome:user_123",
});

await bureau.credits.topup({
  card: { kind: "ephemeral", card_id: card.card_id },
  credits: 100_000,
  source: "creator_reward",
  ref: "content_789",
  idempotency_key: "creator_reward:content_789",
});

Card lists return active Ephemeral Cards by default. Pass include_history: true to include unexpired depleted Cards. Expired Cards are deleted on the next access, while their accounting history remains available through Transaction Entries.