Prepaid Balance Recharge

A currency balance recharge is a one-time top-up to a prepaid actual currency balance. It is similar to a one-time payment initiated with the payment APIs for postpaid main balances.

When making a subscriber or group recharge using the SubMan APIs, you must specify the recharge amount and the subscriber or group wallet must have a prepaid actual currency balance. If you attempt to make a recharge and the wallet does not have a prepaid actual currency balance, an error occurs. If you do not specify a balance resource ID, the prepaid main balance is automatically credited. If there is no prepaid main balance, an error will occur.

Recharge Extensions

You can create a private MDC to define custom fields from the base MtxRechargeExtension MDC. When you make a recharge request using the SubMan APIs described below, specify values for the custom fields. These custom fields are then populated in the recharge event (MtxRechargeEvent) and recharge notification (MtxRechargeNotification). For more information about creating private MDCs, see the discussion about adding a custom MDC in MATRIXX Integration.

Recharge Events

Recharges to subscriber or group prepaid actual currency balances generate an MtxRechargeEvent Event Detail Record (EDR) (event type 30). When a recharge is made using Pay Now, the balance update record in the BalanceUpdateArray in the MtxRechargeEvent EDR includes a negative amount and there is a single charge record. For information about the MtxRechargeEvent EDR, see the discussion about MtxRechargeEvent in MATRIXX Integration.

Recharge Notifications

If notifications are configured, an MtxRechargeNotification is generated (notification types: subscriber_recharge = 66 and group_recharge = 67).
Note: Detailed balance information is included in the notification when a balance is updated as the result of a recharge. For more information about notifications, see the discussion about notifications in MATRIXX Integration.

SubMan APIs

When making a balance recharge, specify that the Charging Server request immediate payment using Pay Now. For more information about Pay Now, see the Pay Now overview in MATRIXX Pay Now.

You can adjust the balance end time using the balance recharge SubMan APIs. The following rules apply to end time adjustments.
  • The End Date Adjustment Type value in the balance definition must be set to Allow to be able to extend the end date using the SubMan APIs.
  • End time adjustments only apply to simple and periodic G/L balances in a subscription or group wallet. They do not apply to virtual balances.
  • When the end time of a periodic balance is adjusted, the change is applied to the entire periodic balance and not to an individual balance interval.
  • The end time can be changed to a time that is earlier or later than the current end time, but must be later than the current start time and the time of the adjustment event.
  • You can configure the system to allow the balance end time of a simple or periodic G/L balance to be set in the past by answering yes to the create_config.info question "GLOBAL: Should a manual balance adjustment allow the end time be set in the past (y/n)?"
    • The end time cannot be later than the current time (now) if you have answered n to the configuration question.
    • The end time cannot be later than the current time (now) if you have answered y to the configuration question, and you have attempted to set a balance in the past that is not a simple or periodic balance.
  • On-demand and aggregated balances can have their end time extended into the future but not into the past.
  • The end time can be an absolute value, such as 4 weeks. You cannot set the end time in the past using a relative value.
  • When extending the end time of an aggregated G/L balance, the end time of all aggregated balances above it will be extended if they are earlier than the new end time. Virtual balances above and below it in the hierarchy are adjusted.
  • Notifications are not sent when a balance end time is changed.
Note: If a balance resource ID is not specified for the recharge operation, then the end time of the main (prepaid) balance is extended if the other rules for end time extensions are met.

Status Life Cycles

The MtxStatusConditionRecharge status life cycle condition can be used to automatically transition a life cycle state when a recharge is made. For more information about using the SubMan APIs to recharge a subscriber or group prepaid currency balance, and how to use recharge conditions and activities in status life cycles, see the discussions about status life cycles and status conditions in MATRIXX Subscriber Management API.