Implementation Guide for Oracle Self-Service E-Billing > Payment Processing > About Recurring Payment Processing >

Functions of the Recurring Payment User Interface

The recurring payment UI lets users insert, update, or delete a recurring payment and view a list of recurring payments. Figure 11 illustrates the objects involved in these actions.

Figure 11. Objects Involved in the Recurring Payment User Interface

Retrieving and deleting recurring payments from the Oracle Self-Service E-Billing database is straightforward, so the next topics discuss what happens when a recurring payment is inserted or updated.

Insert Recurring Payment from the UI

Figure 12 demonstrates what happens when a recurring payment is inserted into Oracle Self-Service E-Billing database using the UI.

Figure 12. Recurring Payment Inserted into the Oracle Self-Service E-Billing Database Using the User Interface

The RecurringPaymentUtil.calculateInternal() Method

The RecurringPaymentUtil.calculateInternal() method calculates the next_pay_date and status of the recurring payment before it is being inserted into Oracle Self-Service E-Billing database. This method calculates the internal states of recurring payment differently for insert and update. For the insert operation, this method performs the following tasks:

1. Call init() method: this method sets some of the recurring payment fields.
   • If the user chooses to end recurring payment by maximum number of payments,then set end_date to 01/01/3000 00:00:00.
   • If the user chooses to end recurring payments by a fixed date, then set the max_num_payments in java.lang.Integer.MAX_VALUE.
   • Set last_pay_date to 01/01/1970 00:00:00. This means no bill has been paid.
   • Set bill_scheduled to Y if the recurring payment is fixed amount and fixed date. Note, in this case, the flag is always true because whenever a payment is made, the next payment is calculated. It has the same effect as making the next bill available immediately.
   • Set last_process_time to start_date, which by default must be tomorrow or later. This means that any bills indexed through today (inclusive) will not be picked up by recurring payment. The recurring payment UI checks whether there are unpaid bills when a recurring payment is setup, and reminds the user to make a one-time payment to pay the outstanding bill.
2. Call the checkSynchronization method: Checks whether any required information is missing from recurring payment before inserting it into the Oracle Self-Service E-Billing database.
3. Check whether the recurring payment has expired by checking the current number of payments against maximum number of payments. Note, this check always return false for insert case.
4. Calculate the next_pay_date by calling one of calculateMonthly(), calculateQuarterly(), calculateWeekly() or calculateBeforeDue() depending on whether pay_interval is monthly, quarterly or weekly or before_due respectively.
   • Call calculateMonthly() when pay_interval is monthly.

     This method calculates the next pay date, which is based on last_pay_date, start_date and day_of_pay_internal. Because last_pay_date is 01/01/1970, the next_pay_date is the nearest date with day_of_pay_internal after the start_date. If date_of_pay_internal is 29, 30 or 31 and there is no such date in that month, then the last day of that month is used. After next_pay_date is calculated, it is checked against the end_date. If next_pay_date passes the end_date, then the status of the recurring payment is set to inactive.

     The following table displays some examples of how next_pay_date is calculated:

     Day_of_pay_interval	Start_date	Next_pay_date
     1	Sep 10	October 1
     10	Sep 10	September 10
     15	Sep 10	October 15
     31	Sep 10	September 30

   • Call calculateQuarterly() when pay_interval is quarterly. This works similar to monthly.
   • Call calculateWeekly() when pay_interval is weekly. This works similar to weekly.
   • Call calculateBeforeDue() when pay_interval is before due. There is no bill yet (bill due date is null), the recurring payment status is set to active and the next_pay_date is set to 01/01/3000.

Update Recurring Payment from the UI

This topic assumes that the UI prevents a user from updating a recurring payment from fixed date to before due date or conversely. If the UI is changed to allow a user to do so, then the behavior of recurring payment is not tested.

Figure 13 demonstrates what happens when a recurring payment is updated using the UI into the Oracle Self-Service E-Billing database.

Figure 13. Recurring Payment Inserted into the Oracle Self-Service E-Billing Database Using the User Interface

The RecurringPaymentUtil.calculateInternal() Method

The RecurringPaymentUtil.calculateInternal() method calculates the next_pay_date and the status of the recurring payment before it is inserted into Oracle Self-Service E-Billing database. Note that this method is also used for update by the back-end job.

The following example shows how this method is processed starting with iRecurringPaymentLog.update():

1. Calls IRecurringPaymentLog.update()
2. Calls RecurringPaymentUtil.calculateInternal()
3. Calls checkSynchronization() method to check whether the information required for recurring payment is present.
4. If checkSynchronization() generates an exception indicating missed information, then:
   • Call synchronize() method to read the missed information from the Oracle Self-Service E-Billing database and populate the missing information into the recurring payment object.
   • Calls checkSynchronization() again to make sure the required information has been populated.
   • Calls init() method: unlike the insert operation, this method checks whether the recurring payment has started or not by checking the last_pay_date (01/01/1970 means not started yet) and then sets the Last Process Time to the start_date of the recurring payment if the recurring payment has not been started. The Last Process Time will not be updated if recurring payment has been started.
5. Checks whether the recurring payment has expired by checking the current number of payments against maximum number of payments. If true, then set the recurring payment as inactive and return.
6. Calculates next_pay_date and recurring payment status by calling one of calculateMonthly(), calculateQuarterly() or calculateWeekly() based on pay_interval of monthly, quarterly or weekly.
   1. Calls calculateMonthly() when pay_interval is monthly, to calculate the next pay date.
   2. If the last_pay_date is 01/01/1970, then the next_pay_date is calculated based on the start_date and day_of_pay_interval. It is set to the nearest date with day_of_pay_interval as day of month after the start_date. This is the same as the insert case.
   3. If the last_pay_date is not 01/01/1970, then that means that recurring payment has started, so the next_pay_date is calculated based on the last_pay_date and day_of_pay_interval. It is set to the date one month after the last_pay_date. The calculation does not depend on the current date. For example, if the recurring payment job runs today on October 1, the last_pay_date is Aug 30 and day_of_pay_interval is 30, then the next_pay_date will be Sep 30 (not October 30 ) even though this date is in the past. In the case of fixed date and pay amount due, this can pose a problem if there is no bill for a certain month, then the pay date will be in the past. To fix the problem, the recurring payment job will move the last_pay_date ahead by one month if there is no bill for that month.
   4. If day_of_pay_interval is 29, 30 or 31 and there is no such date in that month, then the last day of that month is used.

      After next_pay_date is calculated, it is checked against the end_date and if it passes the end_date, the status of the recurring payment is set to inactive.

   • Calls calculateQuarterly() when pay_interval is quarterly. This works similar to monthly.
   • Calls calculateWeekly() when pay_interval is weekly. This works similar to weekly.
   • Calls calculateBeforeDue() when pay_interval is before_due:

     First check whether the recurring payment has been synchronized (bill due date not null) and if so, then sets the status to Active and next pays date to 01/01/3000 and return.

     Calculates the proposed next pay date by current bill due date and day_of_internal.

     If the proposed next_pay_date is before start_date, then sets the status of recurring payment to active and next_pay_date to 01/01/3000 and return: the bill will not be paid in this case because it falls outside the effective period of the recurring payment.

     If the proposed next pay date is after end_date, then sets the status of recurring payment to inactive and set the next_pay_date to 01/01/3000 and return.

     Otherwise, sets the status of the recurring payment to active and set its next_pay_date to the proposed next pay date.