Threshold-Triggered Automatic Recharge

Using the SubMan APIs, you can configure a balance instance with a threshold that triggers an automatic recharge request. For example, when the available balance in the prepaid main balance becomes less than $5, the Payment Service requests a $50 recharge to the prepaid main balance.

In RechargeData in the SubMan APIs, you can specify a recharge amount (required) and payment method (optional). If you do not specify a payment method, the current default payment method for system-initiated charges at the time of the recharge is used. If the default system-initiated payment method is not set, the current default payment method is used.

Use the following SubMan APIs to add or modify a recharge definition in a balance threshold:
  • MtxRequestSubscriberAddThreshold
  • MtxRequestGroupAddThreshold
Use the following SubMan APIs to query the recharge threshold definitions for all balances or a specific balance instance:
  • MtxRequestGroupQueryThresholdRechargeDefn
  • MtxRequestSubscriberQueryThresholdRechargeDefn
Use the following APIs to remove a threshold recharge definition from a threshold:
  • MtxRequestGroupRemoveThreshold
  • MtxRequestSubscriberRemoveThreshold

For more information about these APIs and the REST version of the SubMan APIs, see MATRIXX Subscriber Management API.

When a balance threshold is reached or crossed when a balance increases (for example, from -100 to -5), MATRIXX Charging Application generates a recharge request to the Payment Service to recharge the prepaid main balance. For each balance or meter instance, a pricing administrator can configure multiple balance thresholds. A threshold that triggers an automatic recharge cannot be a recurring threshold or balance floor threshold. The balance instance cannot be a virtual balance.
Note: If a threshold is locked, you cannot override it with the AddThreshold APIs. However, you can specify the recharge data and threshold ID.

When a threshold is reached or crossed when a balance increases, the MATRIXX Charging Application checks if the current life cycle status of the subscriber or group allows automatic recharge. If the life cycle status allows automatic recharge, MATRIXX Charging Application generates a recharge request to the Payment Service for the recharge amount. If the payment authorization fails because due to insufficient funds, no retry is attempted. If automatic recharge is not allowed in the current life cycle status, automatic recharge does not occur.

Event Detail Record and Notifications

If notifications are enabled for balance thresholds, MATRIXX Engine generates a balance threshold notification (MtxBalanceThresholdNotification). If events are enabled for balance thresholds, a balance threshold Event Detail Record (EDR) is generated. For information about notifications, see the discussion about the Notification Framework in MATRIXX Integration.

For an automatic recharge request, if the recharge operation is successful, a recharge event and payment authorization event are generated and linked. If notifications are configured, a recharge notification is generated. The recharge event and notification contain a Reason field that indicates that the recharge is a system-generated automatic recharge and they include additional information about the balance threshold that triggered the automatic recharge.