Skip to content

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:

TypeDescription
CREDITMoney added (e.g. admin top-up)
DEBITMoney deducted (e.g. applied at checkout)
REFUNDMoney 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.

  1. 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.
  2. 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.
  3. 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.

FieldTypeDescription
source_currencystringCurrency to convert from
target_currencystringCurrency to convert to
source_amountdecimalAmount in source_currency to convert
suggested_rate / suggested_target_amountdecimalExchange rate and resulting amount suggested at request time
final_rate / final_target_amountdecimalExchange rate and amount actually applied on execution (set once executed)
statusenumPENDING, COMPLETED, or REJECTED
rejection_reasonstringWhy the request was rejected, including automatic expiry