Balance Transfers

A balance transfer is a subscription 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.
The balance transfer operation generates a MtxBalanceTransferEvent for the event initiator. This event type contains optional Reason and Info fields that are populated from the balance transfer API and a field that indicates if the transfer was to or from the event initiator. The Reason field is also copied to the MtxEventChargeNormalizationInfo MATRIXX Data Container (MDC) to be used for normalizations on General Ledger (GL) account data. In addition, when an amount is transferred from a balance:
  • If the balance is a currency, revenue is recognized according to the GL information in the MtxBalanceTransferEvent Event Detail Records (EDRs) (both primary event and secondary event).
  • If the balance is a non-liability asset, there is no action because no GL information is generated in MtxBalanceTransferEvent EDRs.
  • If the transferred balance is a liability asset, the asset and its deferred revenue amount is transferred from the source wallet to the target wallet. Revenue is recognized later when the transferred asset is consumed. The GL account names and transaction type specified in the GL information in the transfer event override those specified in the GL information from the original purchase event.
Note: Balance transfers do not generate threshold notifications and do not trigger auto-expiration.

For more information about auto-expiring balances, see MATRIXX Pricing and Rating.

For information about normalizing on the transfer reason for GL accounts, see MATRIXX Pricing and Rating.

Failed Balance Transfers

A balance transfer failure event is generated only for insufficient funds or balance floor reached. There are a number of checks performed for balance transfers. While multiple errors may occur, a balance transfer failure event (MtxBalanceTransferFailureEvent) is generated only in the following cases:
  • There is not enough in the sending balance to transfer (insufficient funds).
  • The recipient balance can not accept the additional funds (balance floor reached).
Note: The balance_transfer_failure event should be enabled in pricing for this event to be generated as it is created in the disabled state.

For more information about event failure, see the discussion about event generation for failed transactions in MATRIXX Pricing and Rating. For more information about MtxBalanceTransferFailureEvent, see the discussion about MtxBalanceTransferFailureEvent in MATRIXX Integration.