Balance Transfers

A balance transfer is a subscriber management transaction that moves an amount from one balance instance to another balance instance.

The following rules apply to balance transfers:
  • Transfer balances between any two prepaid G/L balance instances of the same balance unit, for example, minutes or megabytes.
  • The source balance and the target balance can be in the same wallet or in different wallets.

    For example, a subscription belonging to a family sharing group can transfer 100 voice minutes from his or her minutes balance to the group minutes balance, or to another family member. Note that with this example the balances are in the same group hierarchy, but this is not a requirement.

  • The source and target balances can be simple balances or periodic balances.

    For periodic balances, only the current balance interval is impacted. Transfers to or from on demand balances are not supported.

  • The source balance can be expired. The target balance cannot be expired.
  • You cannot transfer balances between an actual currency balance and a pseudo-currency balance.

    Transfers must be from an actual currency balance to an actual currency balance or from a pseudo-currency balance to a pseudo-currency balance. For more information about actual currency balances and pseudo-currency balances, see the discussion about actual currency and pseudo-currency balances.

  • When MATRIXX Engine is configured to include GL information in events, the source and target balances must be either both liability assets or both non-liability assets.

    For example, you cannot transfer a liability asset balance to a non-liability asset balance.

  • The amount being transferred must be specified either as a positive absolute value or as a percentage of the available amount in the source balance.
    The entire amount in the source balance is available for transfer, regardless of any reservations against that amount. However, if the specified transfer amount exceeds the available amount, the operation will fail. Any transferred amount that had been reserved in the source balance will no longer be reserved in the target balance.
    Note: If the transfer amount removes the entire amount from the source balance, and that balance is configured to automatically expire, the balance is not expired upon completion of the transfer request. The next time Task Manager runs, as configured during MATRIXX Engine configuration, Task Manager processes the expiration.
Because the target balance amount decreases (for prepaid balances, the balance amount is negative), after a balance transfer, customers can decide whether to also adjust the credit floor of the target balance during the transfer operation. The credit floor is the starting value from which to calculate percentage threshold notification amounts, and is used to manage notifications for prepaid balances. The credit floor adjustment options are:
  • No adjustment (1)
  • Adjust by the transferred amount (2)
  • Adjust by source credit floor amount (3)
The default is No adjustment. The adjustment amount for each option is calculated as described in Calculating Adjustment Amounts.
Table 1. Calculating Adjustment Amounts
Option Behavior
1 No credit floor amount is calculated and the credit floor of the target balance is not adjusted.
2 The amount by which to adjust the target balance's credit floor is calculated by using the transferred amount.
3 The amount by which to adjust the target balance's credit floor is calculated based on whether the transfer amount is a percentage or an absolute value.
  • If the transfer amount is a percentage, the calculation uses the percentage of the source credit floor amount. For example, if the source credit floor is 10 MB and the transfer amount is 10%, the amount by which to adjust the target balance's credit floor is 1 MB (10% of 10 MB = 1 MB).
  • If transfer amount is an absolute amount other than 0, the calculation used is: 
    (transferred amount ÷ source gross amount) × source credit floor amount
    For example, say the source credit floor is 1000 MB, with 500 MB in the source balance, and 200 MB are transferred. The calculation is: 
    200 MB ÷ 500 MB = .4 MB
.4 MB × 1000 = 400
    The amount by which to adjust the target credit floor is 400 MB.
  • If the transfer amount is an absolute amount of 0, the credit floor of the target balance is adjusted by an amount of 0.

After the credit floor adjustment amount is determined, the way it is applied to the target balance credit floor is based on whether the target balance is a simple balance or a periodic balance and the Grant Credit Floor Adjust value in the balance template:

  • Simple balances — If the Grant Credit Floor Adjust value that is set in the balance template is Grant Amount plus Balance Amount, the new credit floor is equal to the current balance amount plus the calculated credit floor adjustment amount. If the Grant Credit Floor Adjust value is Actual Grant Amount, the new credit floor is equal to the calculated credit floor adjustment amount.
    The simple balance Grant Credit Floor Adjust values are:
    • Grant Amount plus Balance Amount
    • Grant Amount
  • Periodic balances — The new credit floor is equal to the current credit floor plus the calculated credit floor adjustment amount.
Note: Balance transfers do not generate threshold notifications and do not trigger auto-expiration.

For information about using the SubMan APIs to transfer a balance amount, see the discussion about balance transfers in MATRIXX Subscriber Management API.