Primary 与 Ephemeral Cards — Downcity Payments

每个用户只有一张永久 Primary Card。一个用户最多有 100 张未过期且有余额的 Ephemeral Card，适合新用户体验、活动或创作者奖励。expires_at 必须是 ISO 8601 时间，并会统一保存为 UTC。

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

给现有 Card 增加额度：

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 列表只返回未过期且有余额的 Ephemeral Cards；传入 include_history: true 可查看尚未过期但已经耗尽的 Card。过期 Card 会在下一次访问时自动删除，历史账务仍保留在 Transaction Entries 中。