redeem_code 兑换

redeem_code 适合这种场景：

• 活动赠送 credits
• 人工补偿余额
• 发放一次性礼品码

它和 topup 的区别很简单：

• topup 是“先创建充值单，后确认到账”
• redeem_code 是“用户输入 code 后，校验通过就立刻到账”

管理侧创建 redeem_code

const issued = await admin.balance.redeemCodes.create({
  amount: 500,
  note: "launch gift",
});

返回结果里会包含：

• redeem_code_id
• amount
• unit
• status
• code
• code_mask

注意：

• code 明文只在创建时返回一次
• 后续列表接口只会返回 code_mask

用户侧兑换 redeem_code

const result = await user.service("balance").action("redeem-codes/redeem").invoke({
  code: "ABCD-EFGH-JKLM-NPQR",
});

兑换成功后会发生三件事：

• 把这个 redeem_code 标记为 redeemed
• 给当前用户余额直接加款
• 写一条 redeem 类型的流水

管理侧查看与停用

查看：

const items = await admin.balance.redeemCodes.list({
  status: "active",
});

停用：

await admin.balance.redeemCodes.disable({
  redeem_code_id: issued.redeem_code_id,
  note: "expired",
});

停用后的 redeem_code 不能再被兑换。

什么时候选 redeem_code，什么时候选 topup

选 redeem_code：

• 你要发给用户一个可输入的礼品码
• 你不依赖支付回调
• 你希望兑换时直接到账

选 topup：

• 你要先创建订单
• 你需要等支付平台或 admin 确认
• 你要把“发起充值”和“确认到账”拆开

常用入口

• POST /v1/balance/redeem-codes/redeem
• GET /v1/balance/redeem-codes
• POST /v1/balance/redeem-codes/create
• POST /v1/balance/redeem-codes/disable