Subscriber Scheduled Recharge

A subscriber scheduled recharge is initiated on a schedule that you define using the subscriber or group RechargeSchedule SubMan APIs.

A recharge cycle period can occur in the following time intervals where n is greater than or equal to 1:
  • n weeks
  • n months
  • n years
Recharge Schedule Information describes the recharge schedule information.
Table 1. Recharge Schedule Information
Field Type Description
NextScheduledRechargeTime Datetime The next time a scheduled recharge is to be processed based on the recharge schedule of the subscriber.
CycleDefn Struct Cycle definition of the scheduled recharge (MtxRechargeCycleInfo).
Amount Decimal The amount of the scheduled recharge.
PaymentMethodResourceId Unsigned int32 The resource ID of the payment method for the scheduled recharge.
EndTimeExtensionOffsetUnit Unsigned int32 Units relative to the recharge time to extend the EndTime of the prepaid main balance if the current EndTime is less than the extended time.
  • 1 = Hours
  • 2 = Days
  • 3 = Weeks
  • 4 = Months
  • 5 = Years
  • 6 = Minutes
For more information, see Balance Extension.
EndTimeExtensionOffset Unsigned int32 The number of units relative to the recharge time to extend the EndTime of the prepaid main balance if the current EndTime is less than the extended time.
ScheduledRechargeNotificationProfileId Unsigned int64 The pricing ID of the notification profile. Determines when advance notifications are generated for upcoming scheduled recharge.
Important: You can define only one recharge schedule per subscriber or group. If you define a new recharge schedule for a subscriber or group that has an existing recharge schedule, the existing recharge schedule is replaced.

At the scheduled recharge time, the Charging Server generates a request to the Payment Service to get the funds specified by the recharge amount.

RechargeSchedule APIs

The APIs listed in Subscriber Management SubMan APIs create, query, and remove subscriber and group recharge schedules. When configuring the recharge schedule with the SubMan APIs, MtxRechargeCycleData has the following default values:
  • PeriodType: No default value.
  • PeriodCoef: 1.
  • CycleTimeOfDay: 00:00:00.
  • CycleOffset: 1. Sets how far into the period the offset is. For example:
    • For a recharge schedule of every month on the 8th, PeriodType=2 (monthly), PeriodCoef=1, and CycleOffset=8.
    • For a recharge schedule of every week on Monday (2nd day of the week), PeriodType=1 (weekly), PeriodCoef=1, and CycleOffset=2.
    For weekly periods, the offset values are:
    • Sunday (1)
    • Monday (2)
    • Tuesday (3)
    • Wednesday (4)
    • Thursday (5)
    • Friday (6)
    • Saturday (7)
Table 2. Subscriber Management SubMan APIs
API Description
MtxRequestSubscriberAddRechargeSchedule Defines a recharge schedule for a subscriber.
MtxRequestSubscriberModifyRechargeSchedule Modifies the existing recharge schedule associated with a subscriber.
MtxRequestSubscriberRemoveRechargeSchedule Removes the recharge schedule associated with a subscriber.
MtxRequestSubscriberQueryRechargeSchedule Returns the recharge schedule associated with a subscriber.
MtxRequestGroupAddRechargeSchedule Defines a recharge schedule for a group.
MtxRequestGroupModifyRechargeSchedule Modifies the existing recharge schedule associated with a group.
MtxRequestGroupRemoveRechargeSchedule Removes the recharge schedule associated with a group.
MtxRequestGroupQueryRechargeSchedule Returns the recharge schedule associated with a group.

The response (MtxResponseRechargeScheduleInfo) from the AddRechargeSchedule, ModifyRechargeSchedule, and QueryRechargeSchedule APIs includes the calculated time when the recharge occurs based on the recharge schedule.

For information about using the RechargeSchedule APIs, see the discussion about recharge in MATRIXX Subscriber Management API.

Balance Extension

If the EndTimeExtensionOffsetUnit and EndTimeExtensionOffset fields are set in the recharge schedule data, MATRIXX Charging Application calculates an end time extension from the recharge time using the specified offset (for example, 60 days from recharge time). If the extended time is beyond the current end time of the prepaid main balance and the balance template allows end time adjustment, the balance end time is extended. If the extended time is before the current end time of the prepaid main balance or the balance template does not allow end time adjustment, the balance end time is not extended.

For example, assume a subscriber defines a recharge schedule to recharge $10 on the 5th day of each month with an end time extension offset of 1 month from the recharge time. The balance's current end time is June 1, 2018. When the scheduled recharge occurs on April 5, 2018, the balance's end time is not adjusted. However, when the scheduled recharge happens on May 5, 2018, the balance's end time is extended to June 5, 2018.

Status Life Cycles

In status life cycles, you can enable and disable automatic recharge with the MtxStatusPolicyAutoRecharge status policy. If automatic recharge is allowed for a subscriber or group, the recharge is processed. If it is not allowed, automatic recharge does not occur and the next recharge time is updated; the status is checked again at the next recharge time. Status notifications are independent of the recharge notifications described in the following section. For more information about status life cycles, see the discussion about status life cycles in MATRIXX Subscriber Management API.

Recharge Notifications

Advance notifications for subscriber scheduled recharges can be sent according to notification profiles configured in My MATRIXX. For more information about creating notification profiles, see the discussion about creating a billing profile template in My MATRIXX Help.

For scheduled recharges, notifications can be generated in the following situations:
  • Advance Notification — You can specify a notification profile ID using the RechargeSchedule SubMan APIs to set when advance notifications are generated for an upcoming scheduled recharge. If the subscriber_scheduled_recharge and group_scheduled_recharge notification types are enabled, MATRIXX Charging Application generates a recharge notification (MtxScheduledRechargeNotification). The notification has the recharge time, recharge amount, payment method, and the balance EndTime extension if configured.
  • Successful Recharge — If the subscriber_recharge or group_recharge notification types are enabled and the recharge is successful, a recharge notification (MtxRechargeNotification) is generated.
  • Failed Recharge — If the subscriber_recharge_failure or group_recharge_failure notification types are configured, when payment authorization fails during the recharge, a notification (MtxRechargeFailureNotification) is generated.
Note: Automatic recharge notifications are per-subscriber while recurring processing notifications are per-cycle. For more information, see the discussion about cycle processing in MATRIXX Pricing and Rating.

For more information about notifications, see the discussion about the MATRIXX Notification Framework in MATRIXX Integration.

Recharge EDRs

When a scheduled recharge operation is successful, an MtxRechargeEvent EDR is generated with a Reason field value scheduled recharge. The Reason field is included also in recharge success and failure notifications. You can normalize on the Reason field for general ledger purposes. For information about general ledger normalization, see the discussion about normalizers for general ledger tables in MATRIXX Pricing and Rating.