Purchased Item Recurring Processing Failure

In My MATRIXX, configure if recurring processing for a purchased item (product offer or bundle) succeeds or fails if there is insufficient credit. Recurring processing succeeds or fails for an individual purchased item cycle.

When the cycle type is purchased item cycle, the CyclePurchasedItemAttr field (MtxPurchasedOfferExtension type) in MtxRecurringFailureNotification populates with any custom attributes.
Note: If a purchased item is in a recoverable state when recurring processing fails, a recurring failure notification and event are not generated.

My MATRIXX

Allowing recurring processing failure at purchase is disabled out-of-the-box. You must configure it in the product offer or bundle cycle data properties.

To handle recurring processing failure when Recurring Failure on Purchase Allowed is true, in the product offer or bundle template cycle data properties, configure the priority field to specify that recurring processing be attempted for lower-priority purchased items whose cycle periods begin at the same time. If the lower-priority purchased item cycles have lesser charges, they might succeed.

Recurring Failure on Purchase Allowed can prevent recurring charges and grants being applied to lower priority purchased items when there is a recurring failure. It also prevents recurring charges and grants being applied for any purchased item cycle periods that begin later. This setting does not stop recurring processing for balance cycle and billing cycle periods.
Note: The cycle data priority setting is separate from the priority setting in product offer templates for usage rating. For information about offer priority rating, see the discussion about calculating offer priority during rating in MATRIXX Pricing and Rating.
During purchases with the SubMan APIs, you can override the Recurring Failure on Purchase Allowed property configured in My MATRIXX with the IsRecurringFailureAllowed field in the API. In My MATRIXX, you must check the Recurring Processing Failure at Purchase Override property in the product offer or bundle cycle data properties to allow the override.
Note: The IsRecurringFailureAllowed property does not apply to denials. It is only applied due to lack of funds to pay for charges.
For more information about configuration in My MATRIXX, see My MATRIXX Help.

SubMan Purchase Offer APIs

If you do not set the IsRecurringFailureOverrideAllowed to true in the purchase request, the setting defined in the product offer or bundle cycle data properties in My MATRIXX is used.

You can configure the IsRecurringFailureAllowed field in the MtxRequestSubscriberPurchaseOffer, MtxRequestGroupPurchaseOffer and MtxRequestDevicePurchaseOffer for each catalog item purchase. If IsRecurringFailureOverrideAllowed is not true, and IsRecurringFailureAllowed is specified in the purchase request, the purchase request fails. If the purchase request succeeds with recurring failure, the IsRecurringFailure field in MtxPurchaseInfo is set to true and a purchase event is generated. If a recurring failure notification profile is defined for purchase item or bill cycle failures, a notification is generated for the cycle failure.

When you purchase an offer in active state, the recurring charge for the initial cycle is applied (recurring processing for the first cycle is part of the purchase operation). If the IsRecurringFailureAllowed parameter is true, and the recurring charge cannot be applied, then the PurchaseOffer API returns success and the offer is purchased (purchase/activation charges are applied), but there is no recurring charge or recurring grant. Setting IsRecurringFailureAllowed to true gives a subscriber more time to pay for the recurring charge.

When an offer is purchased in pre-active state, the IsRecurringFailureAllowed parameter is not applicable. If a purchase charge cannot be applied, then the PurchaseOffer API returns failure, regardless of the value of the IsRecurringFailureAllowed parameter.

When you purchase an offer with Pay Now, the amount of the purchase, activation and recurring charges are combined and collected from the Pay Now method. If Pay Now fails, the PurchaseOffer API returns failure, regardless of the value of the IsRecurringFailureAllowed parameter.

Modify Offer SubMan APIs

When using the ModifyOffer APIs to modify the purchased item cycle and ImmediateChange true, recurring processing for the new cycle is performed. If IsRecurringFailureAllowed is false (default) and recurring processing fails, cycle data is not updated and an error message is returned. If IsRecurringFailureAllowed is true and recurring processing fails, cycle data is updated and the call succeeds with the IsRecurringFailure flag set to "true" in MtxResponseModifyOffer. If a recurring failure status condition is defined for the current status of the purchased item, the status transition is triggered as part of API processing.

When the ModifyOffer SubMan API is called to immediately change the cycle definition of a purchased item (in active state), recurring charge for the first cycle after modification is applied. If the IsRecurringFailureAllowed parameter is not True, and recurring charge cannot be applied, then the ModifyOffer API returns failure and the offer is not modified. On the other hand, if the IsRecurringFailureAllowed parameter is True, then the ModifyOffer API returns success – the purchased item cycle is modified, but there is no recurring charge or recurring grant for the first cycle after modification.

The response of the ModifyOffer API includes a field to indicate if recurring failure occurs while the purchased item cycle definition is being changed.

The purchased item cycle definition cannot be modified for a purchased item in pre-active state. When the ModifyOffer SubMan API is called to manually activate a purchased item, the IsRecurringFailureAllowed parameter is not applicable.

The ModifyOffer API does not support PayNow. Recurring charge, if any, cannot be paid by PayNow.

Retrying Recurring Processing

After recurring failure at purchase time, if a user recharges or tops-up a balance so that there is enough credit to pay the recurring charges before the first cycle ends, recurring process is retried.

If the purchase proration type of the product offer or bundle is prorated, when recurring processing is retried for the first cycle, the cycle is prorated and the cycle is from the purchase time to the end time of the cycle.

Cycle Holding Balances

If a purchased catalog item has a cycle with a cycle holding balance, the cycle holding balance is used for purchase recurring processing charges if allow recurring processing failure at purchase is enabled. If the wallet has enough to pay for recurring charges, the required amount is transferred to the cycle holding balance. The amount transferred into the cycle holding balance is then used to pay for the recurring charges. Advice of Charge is used to calculate the required amount to pay for recurring charges (the cost).

If there are insufficient funds in the wallet to pay for recurring charges, the available amount is transferred to the cycle holding balance and reserved for recurring charges. Recurring grants are not applied.

If purchase recurring processing does not succeed, and the subscriber recharges the currency balance before the end of this first recurring period, available funds are transferred to the cycle holding balance. This process continues until there is enough to pay for the recurring charges and the recurring process succeeds, or until the first period ends. During transition to the next period, the reserved amount in the cycle holding balance is forfeited.

The following occurs if recurring processing does not succeed by the end of a recurring period due to insufficient funds and the product offer or bundle has a cycle holding balance:
  • The period is obsolete for rating.
  • The Charging Server generates an MtxPeriodWriteOffEvent Event Detail Record (EDR). The event includes the forfeited amount of the holding balance, and the estimated recurring charge that would be required for recurring processing to succeed.
  • Recurring processing is not attempted again.

For more information about cycle holding balance processing see the discussion about cycle holding balances. For more information about the MtxPeriodWriteOffEvent EDR, see the discussion about EDRs in MATRIXX Integration.

Grace Periods

If a grace period profile is defined for the purchased item cycle, the purchased item enters the grace period after purchase recurring processing failure. The offer life cycle profile must have grace and recoverable offer states defined if there is a grace period profile.

The status transition occurs as part of the purchase operation. If purchase recurring processing eventually succeeds within the grace period window, the cycle period keeps the start and end times that were calculated. If this grace period ends and there is a recoverable period, and recurring processing is successful during the recoverable period, the cycle period times and cycle definition are re-established based on the current time and the configurable time of day settings for the grace period profile. If the recoverable period ends or one is not configured when the grace period ends, the purchased item transitions to inactive state and the EndTime is set to the current time for the relevant purchased offers.

When exiting the grace period, any remaining cycle holding balance funds are forfeited.

Status Transitions

If a recurring failure status condition is defined for the owner of the purchased item, the owner transitions to the corresponding status after purchase recurring processing failure. If recurring processing eventually succeeds, the owner can transition to a new status based on the recurring success status condition.