Prepaid CreditsTop-Ups and Adjustments

Top-Ups and Adjustments

This page covers how credits get into a wallet and out of it by hand: top-ups, adjustments, removing credits, reversing a top-up that was refunded or charged back, and what happens to credits when a subscription ends.

Top-up flow

A top-up is how a customer buys credits. It is an order of type WALLET TOP-UP with one line, Wallet top-up, for the pack price. The line is taxed like a normal line: GST is charged here and nowhere else.

Raise the top-up

In the portal, open the customer, go to the Wallet tab and click Top up. Pick a Credit pack, or A custom amount, then click Raise top-up invoice. See Wallet Tab. Through the API: POST /v2/subscriptions/{id}/wallet/top-ups.

BillHive creates the order, invoice and payment request

The invoice carries the price plus GST. The payment request is created when a gateway order exists.

The customer pays

The customer pays the invoice through the hosted payment page, the gateway or an offline payment. A top-up invoice can only be paid by a payment, never by ordinary credits.

Credits are posted

When the invoice is paid, BillHive posts a Top-up entry for the price paid before tax, and a Bonus entry for the bonus, if the pack has one. Both are linked to the top-up invoice, so posting twice changes nothing.

The wallet is unblocked

If the subscription was blocked for an empty wallet, walletExhausted clears as soon as the credits arrive.

An unpaid top-up posts nothing. A cancelled top-up order posts nothing. A top-up that fails before its invoice exists is cancelled, so no order is left waiting. An invoice that already exists is kept: it can still be paid.

Example, a pack with a bonus

Pack: pay ₹100, get ₹105. GST 18% exclusive.

Top-up invoiceAmount
Wallet top-up₹100.00
GST 18%₹18.00
Total₹118.00

After the customer pays:

EntryAmountExpires
Top-up₹100.00Never
Bonus₹5.00After the expiry days, if set
Balance₹105.00

Rules

  • The wallet takes the subscription’s currency. A top-up in another currency is rejected with currency: the subscription is billed in INR (the subscription’s own currency is named).
  • A pack is chosen by its index (from 0) in the price’s pack list. A custom amount buys exactly its value, rounded to 2 decimals, with no bonus.
  • A top-up needs an active price on the subscription.
  • Only one open top-up order is allowed per subscription at a time for automatic top-ups.

Adjustments

An adjustment adds credits by hand, for example as a goodwill gesture. It is posted as an Adjustment entry, has no GST and never expires.

  1. Open the customer’s Wallet tab.
  2. Click Add credits.
  3. Enter the amount and the reason.

Through the API: POST /v2/subscriptions/{id}/wallet/adjustments, scope CreditMemo.create.

FieldRules
amountA number above 0, rounded to 2 decimals. Error: amount must be greater than 0.
reasonRequired text. Error: reason is required.

There is no negative adjustment. To take credits away, remove an entry (below).

If an adjustment funds a subscription that was blocked, the block is lifted at once, not at the next daily run.

Removing credits

In the Wallet tab, click Remove on an entry. This cancels the entry and zeroes its remaining balance. What was already spent stays spent. The Remove button shows only while the entry is Posted and has credits left.

Through the API: DELETE /v2/subscriptions/{id}/wallet/entries/{memoId}. It returns { "removed": 20 }, the amount taken out. An entry that does not belong to the subscription gives 404 Wallet entry not found.

Chargeback or refund of a top-up

If the customer’s top-up payment is refunded or charged back, no gateway webhook updates the wallet. You call the reversal:

POST /v2/wallet/top-ups/{invoiceId}/reverse (scope CreditMemo.create), where invoiceId is the top-up invoice.

What it does:

  1. Unspent credit is removed. The Top-up entry and its Bonus entry are cancelled and their remaining balance is zeroed.
  2. Spent credit is billed back. The part that was already spent is worked out, counting the bonus as spent first. Anything the customer used beyond the bonus is added as a pending charge named Credits reversed, taxed like a normal line, on the next invoice. Spent is the sum of the entry’s drawdowns.
  3. Running it again changes nothing. A cancelled entry is skipped, and the pending charge records the top-up invoice, so it is added once.

Example. Pack ₹100 → ₹105. ₹40 was spent. The payment is charged back.

StepAmount
Credits left and removed₹65.00 (₹105 − ₹40)
Spent: ₹40, of which the ₹5 bonus counts first₹35.00 of paid credit
Pending charge Credits reversed₹35.00, plus 18% GST = ₹41.30 on the next invoice

Response:

{ "removed": 65, "charged": 35, "alreadyReversed": false }

If no top-up was posted for that invoice, you get 404 No wallet top-up was posted for that invoice.

Carry-over on cancel and expire

Credits belong to a subscription, but they are not lost when it ends.

  1. On cancel or expire, the final bill draws down first, as usual.
  2. Whatever is left stays on the subscription’s entries. The account’s Wallet tab lists it under Carried over from ended subscriptions.
  3. When the account next activates a subscription whose price has packs or a grant, every carried-over entry moves to it. Each move records the old subscription. The entry keeps its kind and its expiry date. The new balance is the carried amount.
  4. A retry cannot move an entry twice.
  5. If the account has no such subscription, the credits wait. Bonus and grant credits still expire on schedule.

Carried-over period grants follow the new subscription’s rollover rule. Credits are never refunded.

Example. Subscription A is cancelled with ₹26.90 left. The account then activates subscription B, whose price has a wallet. B’s balance is ₹26.90, with the same expiry dates.

Limits

  • Wallet credits cannot be refunded or cashed out.
  • There is no negative adjustment.
  • A wallet is not shared across accounts.
  • Credits to the wrong currency are rejected.