To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Represents a recurring payment schedule, such as a subscription or instalment plan, that bills a stored customer token on a fixed cycle. It is created from the payment transaction which first tokenised the customer's card, and holds the amount, currency, frequency and period multiple that decide when the next charge falls due. A scheduled job picks up the schedules whose next date has passed and raises a DueTransaction for each attempt, with the outcome of every attempt recorded as a RecurringTransactionResult. Cancelling a schedule sets its status to CANCELLED and stops further billing without removing the payment history.
Group: Database Entities
Implements: Serializable, Auditable, Relational
Properties
| Property | Returns | Description |
|---|---|---|
| amount | BigDecimal | The amount charged on each cycle, in the currency given by the currency code. It is fixed for the life of the schedule unless an administrator changes it. |
| auditOrg | Organisation | The organisation audit entries for this schedule are recorded against, which is the organisation that owns it. |
| cart | Cart | The cart, that is the original order, which created this schedule. Optional, and null for schedules that were not created from a cart. |
| createTokenTransaction | PaymentTransaction | The payment transaction which set this schedule up and produced the stored customer token. Later charges are made against that token rather than against card details entered again. |
| currencyCode | String | The three letter ISO currency code the recurring amount is charged in, for example NZD. |
| customerToken | String | The token the payment provider issued when the customer's card was first stored, and the credential every later charge is authorised with. Treat it as sensitive and never show it to a participant. |
| frequency | Frequency | The unit of the billing cycle, one of DAILY, WEEKLY, MONTHLY or ANNUAL. It is combined with the period multiple to give the actual interval between charges. |
| id | long | Primary key of this recurring payment schedule, assigned when it is first saved. |
| invoiceDescExpr | String | Optional expression evaluated when each invoice is generated to produce its description. Null means the provider's default description is used. |
| invoiceNumExpr | String | Optional expression evaluated when each invoice is generated to produce its invoice number. Null means the provider allocates the number. |
| nextDate | Date | The date the next charge falls due. It is rolled forward a whole interval after each cycle, and a schedule is picked up for billing once this date is in the past. |
| org | Organisation | The organisation the schedule belongs to, copied from the originating payment transaction. |
| paymentResults | List<RecurringTransactionResult> | The outcome of each billing attempt made against this schedule, in no particular order. |
| periodMultiples | int | How many frequency units make up one billing interval, so a frequency of DAILY with three multiples bills every three days. Must be at least one or rolling the next date fails. |
| provider | String | Name of the payment provider which holds the customer token and processes each charge. |
| purchaser | Profile | The profile who made the original purchase and who is billed on each cycle. |
| startDate | Date | The date the schedule begins. Nothing is charged before this date, and the first charge falls on the first billing interval after it. |
| status | Status | Whether the schedule is still billing, ACTIVE, or has been stopped, CANCELLED. Cancelled schedules are kept for their history and are never picked up as due. |
| website | Website | The website the original purchase was made through, which decides the payment provider settings and branding used for each later charge. |
Methods
getId() · getPurchaser() · setPurchaser(Profile purchaser) · getCreateTokenTransaction() · setCreateTokenTransaction(PaymentTransaction createTokenTransaction) · getStartDate() · setStartDate(Date startDate) · getOrg() · setOrg(Organisation org) · getWebsite() · setWebsite(Website website) · getAmount() · setAmount(BigDecimal amount) · getCurrencyCode() · setCurrencyCode(String currencyCode) · getInvoiceDescExpr() · setInvoiceDescExpr(String invoiceDescExpr) · getInvoiceNumExpr() · setInvoiceNumExpr(String invoiceNumExpr) · getCustomerToken() · setCustomerToken(String customerToken) · getProvider() · setProvider(String provider) · getFrequency() · setFrequency(Frequency frequency) · getPeriodMultiples() · setPeriodMultiples(int periodMultiples) · getPaymentResults() · setPaymentResults(List<RecurringTransactionResult> paymentResults) · getNextDate() · setNextDate(Date nextDate) · getStatus() · setStatus(Status status) · isDue(Date now) · getCart() · setCart(Cart cart) · rollNextDate() · cancelRecurring() · getAuditOrg() · findDueTransactions() · findDueTransactionById(long id)
getId()
Returns: long
Primary key of this recurring payment schedule, assigned when it is first saved.
getPurchaser()
Returns: Profile
The profile who made the original purchase and who is billed on each cycle.
setPurchaser(Profile purchaser)
Returns: void
Sets the profile who is billed on each cycle.
| Parameter | Description |
|---|---|
purchaser | the purchasing profile |
getCreateTokenTransaction()
Returns: PaymentTransaction
The payment transaction which set this schedule up and produced the stored customer token. Later charges are made against that token rather than against card details entered again.
setCreateTokenTransaction(PaymentTransaction createTokenTransaction)
Returns: void
Sets the payment transaction which set this schedule up.
| Parameter | Description |
|---|---|
createTokenTransaction | the originating payment transaction |
getStartDate()
Returns: Date
The date the schedule begins. Nothing is charged before this date, and the first charge falls on the first billing interval after it.
setStartDate(Date startDate)
Returns: void
Sets the date the schedule begins.
| Parameter | Description |
|---|---|
startDate | the date the schedule starts |
getOrg()
Returns: Organisation
The organisation the schedule belongs to, copied from the originating payment transaction.
setOrg(Organisation org)
Returns: void
Sets the organisation the schedule belongs to.
| Parameter | Description |
|---|---|
org | the owning organisation |
getWebsite()
Returns: Website
The website the original purchase was made through, which decides the payment provider settings and branding used for each later charge.
setWebsite(Website website)
Returns: void
Sets the website the original purchase was made through.
| Parameter | Description |
|---|---|
website | the website the purchase was made on |
getAmount()
Returns: BigDecimal
The amount charged on each cycle, in the currency given by the currency code. It is fixed for the life of the schedule unless an administrator changes it.
setAmount(BigDecimal amount)
Returns: void
Sets the amount charged on each cycle.
| Parameter | Description |
|---|---|
amount | the amount billed each cycle |
getCurrencyCode()
Returns: String
The three letter ISO currency code the recurring amount is charged in, for example NZD.
setCurrencyCode(String currencyCode)
Returns: void
Sets the currency the recurring amount is charged in.
| Parameter | Description |
|---|---|
currencyCode | the three letter ISO currency code |
getInvoiceDescExpr()
Returns: String
Optional expression evaluated when each invoice is generated to produce its description. Null means the provider's default description is used.
setInvoiceDescExpr(String invoiceDescExpr)
Returns: void
Sets the expression used to generate the description on each invoice.
| Parameter | Description |
|---|---|
invoiceDescExpr | the invoice description expression, or null for the default |
getInvoiceNumExpr()
Returns: String
Optional expression evaluated when each invoice is generated to produce its invoice number. Null means the provider allocates the number.
setInvoiceNumExpr(String invoiceNumExpr)
Returns: void
Sets the expression used to generate the invoice number on each invoice.
| Parameter | Description |
|---|---|
invoiceNumExpr | the invoice number expression, or null for the provider default |
getCustomerToken()
Returns: String
The token the payment provider issued when the customer's card was first stored, and the credential every later charge is authorised with. Treat it as sensitive and never show it to a participant.
setCustomerToken(String customerToken)
Returns: void
Sets the stored customer token later charges are authorised with.
| Parameter | Description |
|---|---|
customerToken | the token issued by the payment provider |
getProvider()
Returns: String
Name of the payment provider which holds the customer token and processes each charge.
setProvider(String provider)
Returns: void
Sets the payment provider which processes each charge.
| Parameter | Description |
|---|---|
provider | the payment provider name |
getFrequency()
Returns: Frequency
The unit of the billing cycle, one of DAILY, WEEKLY, MONTHLY or ANNUAL. It is combined with the period multiple to give the actual interval between charges.
setFrequency(Frequency frequency)
Returns: void
Sets the unit of the billing cycle.
| Parameter | Description |
|---|---|
frequency | the billing cycle unit |
getPeriodMultiples()
Returns: int
How many frequency units make up one billing interval, so a frequency of DAILY with three multiples bills every three days. Must be at least one or rolling the next date fails.
setPeriodMultiples(int periodMultiples)
Returns: void
Sets how many frequency units make up one billing interval.
| Parameter | Description |
|---|---|
periodMultiples | the number of frequency units per interval, at least one |
getPaymentResults()
Returns: List<RecurringTransactionResult>
The outcome of each billing attempt made against this schedule, in no particular order.
setPaymentResults(List<RecurringTransactionResult> paymentResults)
Returns: void
Sets the recorded outcomes of the billing attempts made against this schedule.
| Parameter | Description |
|---|---|
paymentResults | the payment results to associate |
getNextDate()
Returns: Date
The date the next charge falls due. It is rolled forward a whole interval after each cycle, and a schedule is picked up for billing once this date is in the past.
setNextDate(Date nextDate)
Returns: void
Sets the date the next charge falls due.
| Parameter | Description |
|---|---|
nextDate | the date the next charge is due |
getStatus()
Returns: Status
Whether the schedule is still billing, ACTIVE, or has been stopped, CANCELLED. Cancelled schedules are kept for their history and are never picked up as due.
setStatus(Status status)
Returns: void
Sets the status. Prefer cancelRecurring to stop billing, so the intent is clear.
| Parameter | Description |
|---|---|
status | the new status |
isDue(Date now)
Returns: boolean
Reports whether a charge should now be attempted, which is true when the given time is after both the start date and the next due date.
| Parameter | Description |
|---|---|
now | the time to test the schedule against |
getCart()
Returns: Cart
The cart, that is the original order, which created this schedule. Optional, and null for schedules that were not created from a cart.
setCart(Cart cart)
Returns: void
Sets the cart which created this schedule.
| Parameter | Description |
|---|---|
cart | the originating cart, or null |
rollNextDate()
Returns: void
Rolls the next due date forward by one billing interval, that is the frequency multiplied by the period multiple. It repeats until the new date is in the future, so a schedule that has not run for several cycles catches up to the next real date instead of billing once for every cycle it missed. A frequency of null or a period multiple below one raises a RuntimeException.
cancelRecurring()
Returns: void
Stops further billing by setting the status to CANCELLED. The schedule and its payment history are kept, and the change is only persisted when the surrounding session is flushed.
getAuditOrg()
Returns: Organisation
The organisation audit entries for this schedule are recorded against, which is the organisation that owns it.
findDueTransactions()
Returns: List<DueTransaction>
Loads every due transaction raised against this schedule, that is one row per payment that has fallen due. Queries the database on each call.
findDueTransactionById(long id)
Returns: DueTransaction
Finds one of this schedule's due transactions by its primary key. All of them are loaded first, and a due transaction that does not belong to this schedule is never returned; no match raises a NoSuchElementException.
| Parameter | Description |
|---|---|
id | the primary key of the due transaction |
© 2025 Kademi Ltd