Automatic Recurring Recharge

Optionally configure MATRIXX Engine to automatically recharge a prepaid actual currency balance based on a recurring cycle.

For information about recurring cycles, see the discussion about cycle processing in MATRIXX Pricing and Rating.

Note: Automatic recharge must be enabled in the status life cycle and there must be a main balance.

Rating

Recurring cost is determined by performing recurring rating in advice mode for the upcoming cycle. By default, the recharge amount is the total of all charges to balance instances that are of the same balance class as the prepaid main balance.

Optionally configure if prepaid balance amounts must be deducted from the recurring amount. This feature is not enabled by default and a recharge request for the full amount of the aggregated, recurring charges is submitted to the Payment Gateway Provider. The options are:
  • Configure the recharge amount to be the difference between the aggregated, recurring charges and the current prepaid main balance amount at the time of recurring recharge processing. If there is a sufficient balance amount in the prepaid main balance to cover the aggregated, recurring charges, no recharge request is submitted to the Payment Gateway Provider. For example, when enabled, if the aggregated, recurring amount for upcoming cycles is $12 and the prepaid main balance has a current balance amount of $5 at the time of recurring recharge processing, a recharge request for $7 is submitted to the Payment Gateway Provider.
  • Configure the recharge amount to be the difference between the aggregated, recurring charges and the total current balance amount of prepaid currency balance instances, including pseudo-currency balances, at the time of recurring recharge processing. If there is a sufficient balance amount in those balance instances to cover the aggregated recurring charges, no recharge request is submitted to the Payment Gateway Provider.
  • Configure the recharge amount to be the difference between the aggregated recurring charges and the total current balance amount of prepaid actual currency balance instances at the time of recurring, recharge processing. If there is a sufficient balance amount in those balance instances to cover the aggregated, recurring charges, no recharge request is submitted.

See System Configuration for information about configuring these settings.

Optionally configure MATRIXX Engine to aggregate all recurring charges within a specified time range, not only recurring charges due for cycles with exactly the same start time, so that only one recharge request is submitted to the Payment Gateway Provider. Cycles with a start time that falls within the specified time range are processed at the start of that time range. See System Configuration for information about configuring aggregation.

Aggregation Scenario

In the following example, automatic recurring recharge is configured to happen 2880 minutes (two days) before the start of a cycle period and the time range to aggregate all charges is configured to 1440 minutes (one day). Recurring Recharge Cycles lists the upcoming cycles that are scheduled with their start times and recharge amounts.
Table 1. Recurring Recharge Cycles
Cycle Number Date/Time Recurring Recharge Amount
1 August 3 at 8:00 AM $1
2 August 3 at 2:00 PM $2
3 August 10 at 8:00 AM $3
4 August 10 at 9:00 AM $4
5 August 10 at 6:00 PM $5

On August 1 at 8:00 AM (two days in advance), an automatic recurring recharge is processed. Cycle 1 and cycle 2 are within the one-day time range and the recurring charges of cycles 1 and 2 are aggregated. A recharge request for $3 is submitted on August 1 at 8:00 AM.

On August 8 at 8:00 AM (two days in advance), automatic recurring recharge is processed again. Cycles 3, 4, and 5 are within the one-day time range and the recurring charges of cycles 3, 4, and 5 are aggregated. A recharge request for $12 is submitted on August 8 at 8:00 AM.

System Configuration

To configure automatic recurring recharge and recurring, recharge aggregation, a system administrator must answer the create_config.info questions in Automatic Recharge create_config.py Questions.

Table 2. Automatic Recharge create_config.py Questions
Question Default
Sets the amount of time before the start of a cycle period to submit an automatic recharge request.
Important: By default (0), this feature is disabled.

create_config.info question: Global:How long (in minutes) prior to the start of a cycle period should an automatic recharge request be submitted?

Note: If you set the recurring recharge time far in advance of the time that recurring processing occurs, it is possible that an event can occur that uses the funds from the recharge before recurring processing occurs. This causes recurring processing to fail.
0
Sets the time range that determines the cycles with recurring, aggregated charges allowing the submission of only one recharge request.

If the answer is 0, aggregation only occurs for recurring charges due for cycles with exactly the same start time.

create_config.info question: Global:What is the time range (in minutes) to aggregate all charges due during automatic recurring recharge processing?

0

Sets whether the current balance amount of all prepaid currency balance instances that are of the same class as the prepaid main balance are deducted from the recurring amount.

create_config.info question: Global:Should the current balance amount of all prepaid currency balance instances that are of the same class as the prepaid main balance be deducted from the recurring amount during automatic recurring recharge processing (y/n)?

If the answer is n, the following question is asked.

n
Sets whether the current balance amount of prepaid actual currency balance instances that are of the same class as the prepaid main balance should be deducted from the recurring amount.

create_config.info question: Global:Should the current balance amount of prepaid actual currency balance instances that are of the same class as the prepaid main balance be deducted from the recurring amount during automatic recurring recharge processing (y/n)?

If the answer is n, the following question is asked.

n
Determines whether the current prepaid main balance amount should be deducted from the recurring amount.

create_config.info question: Global:Should the current prepaid main balance amount be deducted from the recurring amount during automatic recurring recharge processing (y/n)?

n
Indicates if the Automatic Retry of Recurring Recharge feature is enabled or disabled. The feature is disabled by default.

create_config.info question: Global:How long (in minutes) after the start of a failed cycle period should an automatic recharge retry request be submitted?

0

SubMan APIs

To determine the next recurring recharge time and payment method for a subscription or group, use the following SubMan APIs:
  • MtxRequestSubscriberQueryRecurringRecharge (Subscribers)
  • MtxRequestGroupQueryRecurringRecharge (Groups)
When configuring the recharge schedule with the SubMan APIs, MtxRechargeCycleData has the following default values:
  • PeriodType: No default value.
  • PeriodCoef: Default is 1.
  • CycleTimeOfDay: Default is 00:00:00.
  • CycleOffset: Default is 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, CycleOffset=8.
    • For a recharge schedule of every week on Monday (2nd day of the week), PeriodType=1 (weekly), PeriodCoef=1, CycleOffset=2.
    For weekly periods, the offset values are:
    • Sunday (1)
    • Monday (2)
    • Tuesday (3)
    • Wednesday (4)
    • Thursday (5)
    • Friday (6)
    • Saturday (7)
To specify a payment method for system-initiated charges, such as automatic recharge, using the following payment SubMan APIs:
  • MtxRequestSubscriberAddPaymentMethod
  • MtxRequestSubscriberModifyPaymentMethod
  • MtxRequestGroupAddPaymentMethod
  • MtxRequestGroupModifyPaymentMethod

To set a default system payment method, set IsSysDefault in the Payment APIs to true.

The default system payment method is used for automatic recharge when it is set. If the default system payment method is not set, the default payment method associated with a wallet is used if it is set.

In addition, you can use the following subscriber and group APIs to set the payment method for system-initiated charges:
  • MtxRequestSubscriberModify
  • MtxRequestGroupModify

To set a default system payment method, set SysPaymentTokenResourceId in the Modify APIs to the resource ID of the payment token.

Optionally, set the ReturnSysDefault field to true in the following subscriber and group SubMan APIs to return only the default payment method for system-initiated charges:
  • MtxRequestSubscriberQueryPaymentMethod
  • MtxRequestGroupQueryPaymentMethod

If there is a recurring recharge retry failure, an MtxRecurringRechargeRetryFailureEvent is generated. In addition, if the Automatic Retry of Recurring Recharge feature is enabled, the recharge amount is calculated again and the recharge request is retried after the configured retry interval. If the request fails, then the notification is generated.

Note: If you modify a purchased item cycle, the current cycle is terminated (either immediately or at the end of the cycle for a deferred modification). A new cycle is created and the cycle start time is set accordingly. Therefore, the next recurring recharge time for the purchased item is recalculated based on the new cycle start time.

Status Life Cycles

In status life cycles, you can enable and disable automatic recharge with the MtxStatusPolicyAutoRecharge policy of the subscription, group, or device. If automatic recharge is enabled, the recharge is processed. If it is not enabled, 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 MATRIXX Subscriber Management API. For information about creating status life cycles, see My MATRIXX Help.

Recharge Notifications

For automatic recurring recharges, notifications can be generated in the following situations:
  • Advance Notification — For automatic recurring recharges, you can assign a notification profile ID in bill cycle templates and product offer cycle data in the Recurring Recharge Notification Profile field to set when notifications are generated for an upcoming recurring recharge. For example, assume the following notification profile is set in the product offer cycle data and that the subscriber_recurring_recharge and group_recurring_recharge notification types are enabled.
    • Recurring Recharge Notification Profile: Two days prior

    If the recurring recharge is configured to occur 1440 minutes before the recurring cycle, a recurring, recharge notification is sent three days before the beginning of the recurring cycle (two days before the recharge). The recharge notification (MtxRecurringRechargeNotification) contains the recharge time, recharge amount, payment method, and cycle information.

  • Successful Recharge — If the subscriber_recharge or group_recharge notification types are enabled and the recharge is successful, this generates a recharge notification (MtxRechargeNotification). The notification includes information about the cycles that were evaluated and included in the total recharge amount. The cycle information is grouped by cycle owners:
    • CycleOwnerInfoArray (an array of MtxRechargeNotificationCycleOwnerInfo)
      • OwnerId
      • OwnerExternalId
      • OwnerType (1 = device, 2 = subscriber, 3 = group)
      • CycleInfoArray (an array of MtxRechargeNotificationCycleInfo for this cycle owner)
        • MtxRechargeNotificationCycleInfo
          • ChargeAmount
          • CycleType (2 = billing cycle, 3 = purchased item cycle)
          • PeriodStartTime
          • PeriodEndTime
          • PeriodIntervalId
          • CatalogItemId (Set if the cycle type is 3 — purchased item cycle.)
          • CatalogItemExternalId (Set if the cycle type is 3 — purchased item cycle.)
          • ResourceId (Set if the cycle type is 3 — purchased item cycle. Value is the resource ID of the purchased item.)
    Important: The total of the individual cycle RechargeAmount values (expressed as a positive decimal value) might not match the actual recharge (expressed as a negative decimal value) if you have configured advance recurring recharge to exclude the available balance amount.
  • 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. The notification includes information about the cycles that were evaluated and included in the total recharge amount. The cycle information is organized in the same way as it is in the MtxRechargeNotification.
    Note: If the Automatic Retry of Recurring Recharge feature is enabled, the recharge amount is calculated again and the recharge request is retried after the configured retry interval. If the request fails, then the notification is generated.

For more information about creating notification profiles in My MATRIXX, see My MATRIXX Help.

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 Event Detail Record (EDR) is generated with a Reason field value recurring recharge that indicates this is a system-generated automatic recharge. The Reason field is also included 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.

The MtxRechargeEvent EDR includes information about the cycles that were evaluated and included in the total recharge amount. The cycle information is grouped by cycle owners:
  • CycleOwnerInfoArray (an array of MtxRechargeEventCycleOwnerInfo)
    • OwnerId
    • OwnerExternalId
    • OwnerType (1 = device, 2 = subscriber, 3 = group)
    • CycleInfoArray (an array of MtxRechargeEventCycleInfo for this cycle owner)
      • MtxRechargeEventCycleInfo
        • ChargeAmount
        • CycleType (2 = billing cycle, 3 = purchased item cycle)
        • PeriodStartTime
        • PeriodEndTime
        • PeriodIntervalId
        • CatalogItemId (Set if the cycle type is 3 — purchased item cycle.)
        • CatalogItemExternalId (Set if the cycle type is 3 — purchased item cycle.)
        • ResourceId (Set if the cycle type is 3 — purchased item cycle. Value is the resource ID of the purchased item.)
Note: The total of the individual cycle RechargeAmount values might not match the actual recharge if you have configured advance recurring recharge to include the current balance value.

For more information about the MtxRechargeEvent EDR, see the discussion about MATRIXX event detail records in MATRIXX Integration.

For information about automatic recurring recharge for external payment requests, see the discussion about balances with external payment requests in MATRIXX Pricing and Rating.