Advice of Charge

MATRIXX Engine supports Advice of Charge (AoC) for usage and non-usage rating.

AoC returns information about balance impacts only for balances that are actual currency balances (cost balances).

Note: When implementing AoC for an offer, MATRIXX Engine expects actual currency balances to be used in the offer charge components. For AoC to produce useful results, ensure that you explicitly set the Actual attribute for the currency balances that are charged in the offer. Otherwise, AoC and functionality that uses AoC (such as recurring advanced notifications) might not work as expected.

Usage Rating

MATRIXX Engine supports the RFC4006 AoC service, which provides information about the cost and the availability of balance for some amount of service for actual currency balances. MATRIXX Charging Application returns cost information only for balances (currency or asset) configured as a cost balance. For information about balances, see the discussion about balances.

Without altering the subscriber state, MATRIXX Charging Application evaluates pricing and balances to determine if there are enough funds to pay for a request. It returns the information back to the Diameter client. For price inquiries, the Diameter client asks MATRIXX Charging Application what the price is for the requested event and MATRIXX Charging Application calculates the information and responds with the price in the Cost-Information AVP if the charges can be fully applied.

Note: According to RFC4006, a single Cost-Information AVP is reported with a single monetary amount indicated by the Currency-Code AVP. If charges include both currency and asset balance classes, Cost-Information reports only the sum of charges to the currency balance class. Otherwise, if charges include one or more asset balance classes, Cost-Information reports only the sum of the charges to the balance class with the lowest ID, with Currency-Code equal to the ID of that balance class. Also according to RFC4006, PRICE_ENQUIRY considers only the rates applied by pricing, not the availability of credit in balances. Because MATRIXX Charging Application allows those rates to vary depending on available balance quantities, it must consider those quantities when determining rates, and it can only report Cost-Information if those quantities are enough to pay for the request in full. Cost information is included in a Gy CCA-E for immediate event charging (IEC) only.

For balance inquiries, the network client asks MATRIXX Charging Application whether the sufficient balance amount is available for a one-time event, and MATRIXX Charging Application determines the quantity and responds with a Check-Balance-Result of NO_CREDIT or ENOUGH_CREDIT, depending on the available balance quantity. If a service type is configured to only authorize usage when the total requested balance quantity is available (the auth_full_request rating option), MATRIXX Charging Application will not authorize service, modify subscriber state, or return Cost-Information for a one-time event that cannot be charged in full. PRICE_ENQUIRY and CHECK_BALANCE always behave as if auth_full_request is true so that they do not report incomplete Cost-Information or indicate ENOUGH_CREDIT when insufficient balance quantity is available. For more information about one-time events, see the discussion about rating one-time events.

Note: For DIRECT_DEBITING and REFUND_ACCOUNT, MATRIXX Charging Application returns Cost-Information for the actual charges applied or refunded. If nothing is charged or refunded, there is no Cost-Information. For PRICE_ENQUIRY, MATRIXX Charging Application returns Cost-Information only if charges can be applied in full.

Non-Usage Rating

When purchasing and canceling catalog items using the SubMan APIs, the SubMan API responses and notifications include a list of updated balances with the following information:
  • Balance ID
  • Owner ID
  • Balance validity
  • Type of balance (main balance, actual currency balance, or cost balance)
  • Total updated amount
  • Current amount
  • A list of update amounts and the update types:
    • 1 — Charge
    • 2 — Discount
    • 3 — Grant
    • 4 — Adjustment
    • 5 — Cancellation Refund
    • 6 — Cancellation Forfeiture
    • 7 — Forfeiture
    • 8 — Usage Refund
    • 9 — Transfer To
    • 10 — Transfer From
    • 11 — Rollover To
    • 12 — Rollover From
    • 13 — Payment
    • 14 — Tax
    • 15 — Cancellation Tax Refund
    • 16 — Usage Tax Refund
    • 17 — Recharge
    • 18 — Payment Refund
    • 19 — Late Charge
    • 20 — Early Termination Charge
    • 21 — Write-Off
    • 22 — Finance
    • 23 — Debt Payment
    • 25 — Tax Payment
    • 26 — Payment Tax Refund
    • 27 — Tax Paid Previously
To prevent bill shock, the PurchaseOffer and CancelOffer SubMan APIs can be called in advice mode (Advice of Charge) to estimate the cost of the purchase or cancelation. Response APIs describes the response SubMan APIs.
Table 1. Response APIs
Response Description
PurchaseOffer APIs When a PurchaseOffer SubMan API is called in advice mode, the response includes estimates for the purchase cost (charge and tax), any recurring charges, the amounts of granted assets, the cost of financing for a given down payment, including the principal amount financed, and the amount and number of installments in the finance contract offer.
CancelOffer APIs When a CancelOffer SubMan API is called in advice mode, the response includes estimates for the cancelation cost (charge and tax), the amount of the refund for any recurring charges, the amounts of forfeited assets, or the early termination charges in the finance contract.

You can modify an offer in advice mode using the group, subscriber, or device modify APIs. When a purchased item cycle is modified immediately, the response (MtxResponseModifyOffer) includes a list of balance impacts associated with the modification, including period termination proration impacts for the previous cycle, new recurring charge and grant impacts for the subsequent cycle, and the period termination, charge, and grant impacts for any purchased items with cycles aligned to the cycle that is modified immediately. For information about the SubMan APIs, see MATRIXX Subscriber Management API.

For more information about modifying a purchased item cycle immediately, see the discussion about immediate alignment change.

Recurring Processing Advice of Charge

The following APIs return an estimate of the recurring charges and grants for all upcoming balance cycles, billing cycles, or purchased item cycles for the specified subscription or group. By estimating recurring charges and grants you can avoid a recurring processing failure for insufficient funds.
Note: The APIs do not estimate charges for recurring pricing components of suspended offers.
  • Java APIs
    • MtxRequestSubscriberEstimateRecurringCharge
    • MtxRequestGroupEstimateRecurringCharge
  • REST APIs
    • GET /subscriber/{SearchTerm}/recurringcharge
    • GET /group/{SearchTerm}/recurringcharge

The response is returned in MtxResponseRecurringChargeInfo and is broken down by cycle. For each cycle, there is a list of impacted balances, impact amounts and impact types (such as charge, tax, grant, and so forth).

In addition to estimating recurring charges and grants for upcoming cycles, the APIs return the required charges and grants for recurring processing of current cycles to succeed if the recurring processing of current cycles failed before. Current cycles are cycles with a cycle start time in the past and a cycle end time in the future. With this information, the required charge amount can be added to the wallet with a recharge, topup, and so forth to complete recurring processing for the current cycles. The Boolean field CurrentCycleWithRecurringFailure in MtxBalanceImpactInfoGroup identifies if a recurring cycle is a current cycle with recurring failure. This field is set only if the SourceEventType field value is 2 (recurring).

The Boolean field IsCycleHolding in MtxBalanceImpactInfo indicates if a simple balance is a cycle holding balance. For information about cycle holding balances, see the discussion about cycle holding balances in MATRIXX Pricing and Rating.

Recurring charges and grants for each upcoming cycle are estimated according to the state of the subscription, group, or device when a SubMan call is issued and the product offer and bundle revisions that are in effect at the beginning of each cycle. Estimated recurring charges are not returned if an upcoming balance cycle is not within the window of a periodic balance. For more information about periodic balance windows, see the discussion about sliding windows for periodic balances and meters in MATRIXX Pricing and Rating. For more information about the SubMan APIs, see MATRIXX Subscriber Management API.

If a billing cycle has been changed, the response includes information that accounts for the pending billing cycle change.