Appearance
Credit Balance
The Credit Balance is a prepaid balance used for refunds and credits. Unlike service balances, it is not tied to a balance type or usage tracking - it simply holds monetary credit.
A customer has one Credit Balance per service × currency combination. Balances are created automatically the first time one is needed (e.g. on a first refund) - no manual setup required.
It is used for two purposes:
- Refunds and credits - when an order is refunded or a subscription is upgraded, the refunded amount is credited here.
- Applied at checkout - if a customer has a Credit Balance in the relevant currency, it is automatically applied to reduce the amount charged to the payment provider.
Key characteristics:
- Always prepaid - it cannot go negative.
- Scoped to a service and currency - a customer can have multiple Credit Balances if they interact with multiple services or have refunds in different currencies.
- Created automatically - no setup needed.
Example
A customer upgrades their subscription mid-cycle. TiruPay calculates a pro-rata refund of €15.00 for the unused days and credits it to their Credit Balance. On their next purchase, the €15.00 is automatically applied and only the remaining amount is charged to their payment method.
Transactions
Every change to the Credit Balance is tracked as a transaction:
| Type | Description |
|---|---|
CREDIT | Money added (e.g. admin top-up) |
DEBIT | Money deducted (e.g. applied at checkout) |
REFUND | Money refunded (e.g. order refund, subscription upgrade pro-rata) |
Each transaction records the balance before and after, plus a reference to what caused it (order, credit note, or manual action).
Freezes
The Credit Balance supports the same freeze mechanism as service balances:
- Full freeze - Prevents all debits. No amount deducted.
- Partial freeze - Deducts a specific amount via a transaction. The remaining balance stays usable.
See Balance Freezes for details on how freezes work and how they are resolved.
Currency Conversion
Since a customer can hold a separate Credit Balance per currency, they may want to move funds from one currency into another - e.g. to consolidate balances after a refund arrived in a different currency than usual. Conversion always goes through an admin-approved request; a customer (or a Service account on their behalf) cannot move funds between currencies directly.
- Request a conversion, specifying the source currency, target currency, and the amount to convert (which may be less than the full balance). The response includes a suggested exchange rate and the resulting suggested target amount - nothing is moved yet.
- An admin reviews the pending request and either executes or rejects it. On execution, the admin can accept the suggested rate or override it by providing either a different exchange rate or a different target amount - the other value is derived automatically.
- Executing debits the source balance and credits the target balance (creating it if it doesn't exist yet); rejecting leaves both balances untouched.
A customer can have at most 5 pending conversion requests open at a time. A pending request that receives no admin decision within 7 days is automatically rejected.
| Field | Type | Description |
|---|---|---|
source_currency | string | Currency to convert from |
target_currency | string | Currency to convert to |
source_amount | decimal | Amount in source_currency to convert |
suggested_rate / suggested_target_amount | decimal | Exchange rate and resulting amount suggested at request time |
final_rate / final_target_amount | decimal | Exchange rate and amount actually applied on execution (set once executed) |
status | enum | PENDING, COMPLETED, or REJECTED |
rejection_reason | string | Why the request was rejected, including automatic expiry |