redeem_code flows

Use redeem_code when you need:

• promotional credits
• manual compensation
• one-time gift codes

The difference from topup is simple:

• topup means "create first, confirm later"
• redeem_code means "user enters a code and balance is credited immediately"

Create a redeem_code from the trusted side

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

The result includes:

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

Important:

• code plaintext is returned only once at creation time
• list APIs only return code_mask

Redeem from the user side

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

On success the service will:

• mark the redeem_code as redeemed
• credit the current user balance immediately
• write a redeem ledger entry

List and disable on the trusted side

List:

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

Disable:

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

A disabled redeem_code can no longer be redeemed.

When to choose redeem_code vs topup

Choose redeem_code when:

• you want a human-entered gift code
• you do not depend on payment callbacks
• you want immediate credit on successful validation

Choose topup when:

• you need an order first
• you wait for a payment platform or admin confirmation
• you want recharge initiation and credit confirmation to stay separate

Common endpoints

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