SubscriptionTopupBalance

Request to topup a subscriber's balance.

The top-up is always a credit on a balance and requires a reference to a voucher that authorizes the top-up. If the top-up is to a periodic balance, only the current period can be topped up. If the top-up is to a virtual (aggregated) balance, the top-up does not roll up to the group G/L balance. You cannot make a top-up to a balance amount meter.

Validity Time Adjustment

A validity time adjustment can be a change to the start time or end time of a balance or meter instance. The time changes can be applied to simple and periodic G/L balances in a subscription or group wallet. They cannot be applied to virtual balances. When the start or end time of a periodic balance is adjusted, the change is applied to the entire periodic balance and not to an individual balance interval.
Note: Start time adjustments cannot be made to top-ups.
The following rules apply to start time adjustments.
  • Start time adjustments only apply to simple and periodic G/L balances in a subscription or group wallet. They do not apply to virtual balances.
  • When the start time of a periodic balance is adjusted, the change is applied to the entire periodic balance and not to an individual balance interval.
  • The start time can be changed to a time that is earlier than the configured start time but not later than it.
  • The new start time must be an absolute value. You cannot change it to be relative to the adjustment request time or the current start time.
  • The start time of an expired simple balance can be changed, but not an expired periodic balance.
  • When extending the start time of an aggregated G/L balance, the start time of all aggregated balances above it will be extended if they are later than the new end time.
  • A private balance start date (StartTime) cannot be modified.
  • Notifications are not sent when a balance start time is changed.

The following rules apply to end time adjustments.

  • The End Date Adjustment Type value in the balance definition must be set to Allow to be able to extend the end date using the SubMan APIs.
  • End time adjustments only apply to simple and periodic G/L balances in a subscription or group wallet. They do not apply to virtual balances.
  • When the end time of a periodic balance is adjusted, the change is applied to the entire periodic balance and not to an individual balance interval.
  • The end time can be changed to a time that is earlier or later than the current end time but must be later than the current start time and the time of the adjustment event.
  • You can configure the system to allow the balance end time of a simple or periodic G/L balance to be set in the past by answering yes to the create_config.info question "GLOBAL: Should a manual balance adjustment allow the end time be set in the past (y/n)?"
    • The end time cannot be later than the current time (now) if you have answered n to the configuration question.
    • The end time cannot be later than the current time (now) if you have answered y to the configuration question, and you have attempted to set a balance in the past that is not a simple or periodic balance.
  • On-demand and aggregated balances can have their end time extended into the future but not into the past.
  • The end time can be an absolute value, such as 4 weeks. You cannot set the end time in the past using a relative value.
  • When extending the end time of an aggregated G/L balance, the end time of all aggregated balances above it will be extended if they are earlier than the new end time. Virtual balances above and below it in the hierarchy are adjusted.
  • A private balance end date (EndTime) can be modified through the MtxRequestSubscriberTopUpBalance SubMan API.
  • Notifications are not sent when a balance end time is changed.
Note: Balance adjustments or top-ups must specify an amount with a decimal precision less than or equal to the decimal precision specified in the balance's template.

REST Example

URL 
Put http://host:port/rsgateway/data/v3/subscription/AccessNumber+5555555555/wallet/12/topup
Request XML 
<MtxRequestSubscriberTopupBalance>
   <Amount>25.00</Amount>
   <Voucher>ABC12345679</Voucher>
</MtxRequestSubscriberTopupBalance>
Response 
<MtxResponse>
    <RouteId>1</RouteId>
    <Result>0</Result>
    <ResultText>OK</ResultText>
</MtxResponse>