Manages the lifecycle of quotes, invoices, purchase orders and other PaymentItemList records, including creation, cloning, status transitions and PDF generation. Also creates and updates related payment transactions, recurring transactions and invoice payments, and fires quote lifecycle events for funnels to react to. Reached from Java via the request context as PaymentManager.class. See QuoteManager and InvoiceManager for more specialised operations on quotes and invoices respectively.

Group: Managers


Properties

PropertyReturnsDescription
nextInvoiceNumberStringGenerates the next available invoice number, retrying past any number already in use. This performs a database lookup and is not a cheap accessor despite its name.
nextPurchaseOrderNumberStringGenerates the next available purchase order number, retrying past any number already in use. This performs a database lookup and is not a cheap accessor despite its name.
nextQuoteNumberStringGenerates the next available quote number, retrying past any number already in use. This performs a database lookup and is not a cheap accessor despite its name.

Methods

createCartFromInvoice(Invoice invoice, ECommerceStore store) · createCartFromInvoice(Invoice invoice, Website website) · createCartFromInvoice(Invoice invoice, Website website, ECommerceStore store) · quoteAccepted(Quote quote) · unAcceptQuote(Quote quote) · markQuoteAsNew(Quote quote) · quoteRejected(Quote quote) · quoteInvoiced(Quote quote) · quoteSent(Quote quote) · cloneQuote(Quote quote, String number) · cloneInvoice(Invoice invoice, String number, Date dueDate) · clonePurchaseOrder(PurchaseOrder purchaseOrder, String number, Date issuedDate) · deletePaymentItemList(Long id) · deletePaymentItemList(PaymentItemList item) · deleteProposal(Proposal item) · getProposalById(Long id) · getInvoiceListStatus(String name) · newInvoiceBean() · newLineItemBean() · getNextInvoiceNumber() · getNextQuoteNumber() · getNextPurchaseOrderNumber() · getPaymentItemList(Long id) · addAttachmentToPaymentItemList(PaymentItemList paymentItemList, String fileName, String hash, String contentType) · deleteAttachmentToPaymentItemList(PaymentItemList paymentItemList, String hash) · getInvoice(Long id) · getInvoiceAsPDF(Invoice invoice) · getPurchaseOrderAsPDF(PurchaseOrder purchaseOrder) · createInvoice(BaseEntity customer, BaseEntity vendor, InvoiceBean invoiceList) · createInvoice(InvoiceBean invoiceList) · createQuote(String number, String title, String description, Date expiryDate, BaseEntity customer, BaseEntity vendor) · createQuote(String number, String title, String description, Date expiryDate, BaseEntity customer, BaseEntity vendor, Lead lead, Proposal proposal) · getQuoteAsPDF(Quote quote) · addLineItem(PaymentItemList paymentItemList, String description, BigDecimal quantity, BigDecimal unitPrice, String account, BigDecimal taxRate, BigDecimal amount, BigDecimal discountRate, ProductSku productSku, BaseEntity supplier) · addLineItem(PaymentItemList paymentItemList, CheckoutLineItem checkoutLineItem) · deleteLineItem(PaymentItemList paymentItemList, LineItem lineItem) · updateLineItem(PaymentItemList paymentItemList, LineItem lineItem) · findLineItemsByProductSku(ProductSku productSku) · markInvoiceAsDraft(Invoice invoice) · markInvoiceAsSent(Invoice invoice) · markInvoiceAsPaid(Invoice invoice) · markInvoiceAsOverdue(Invoice invoice) · findInvoiceByNumber(String number) · findQuoteByNumber(String number) · findPurchaseOrderByNumber(String number) · newPaymentTransaction(Profile createdBy, String paymentProviderAppId) · createRecurringTransaction(PaymentTransaction ptx, String customerTokenId, BigDecimal amount, String currencyCode, Date startDate, Frequency frequency, int multiples, String invoiceNumExp, String invoiceDescExpr, Cart cart) · createRecurringTransactionResult(RecurringTransaction rtx, PaymentTransaction ptx) · findRecurringTransaction(long id) · lookupFrequency(String ru) · lookupFrequency(RepeatUnit ru) · lookupStatus(String status) · findPaymentTransactionsForCart(Cart cart) · findInvoicesForCart(Cart cart) · findPaymentTx(long id) · findRecurringTxForPaymentTx(PaymentTransaction ptx) · makeEWayTokenPayment(RecurringTransaction rtx, CredentialsBean credentialsBean) · newCredentialsBean(String user, String password, boolean sandbox) · resetDueTransaction(DueTransaction dtx) · doRecurringPayment(DueTransaction dtx) · findProposals(Lead lead) · createProposal(Profile customer, List<Quote> quotes) · extraFields() · saveExtraFields(PaymentItemList pil, FormContext fc) · saveExtraFields(PaymentItemList pil, Map<String,String> valuesMap) · extraFieldValues(PaymentItemList pil) · updatePaymentItemList(PaymentItemList pil) · revisePrices(PaymentItemList pil) · findQuote(long quoteId) · findQuoteStatusType(String status) · findInvoicePayment(Long id) · findInvoicePayment(PointsDebit pointsDebit) · findInvoicePaymentLinks(Invoice invoice) · findInvoicePaymentLinks(InvoicePayment invoicePayment) · deletePaymentLink(InvoicePayment invoicePayment, Long id) · deleteInvoicePayment(InvoicePayment invoicePayment) · newInvoicePaymentBuilder() · createPurchaseOrder(String number, String title, String description, Date issuedDate, BaseEntity customer, BaseEntity vendor, PurchaseOrderBean purchaseOrderList)

createCartFromInvoice(Invoice invoice, ECommerceStore store)

Returns: Cart

Creates a pending cart pre-populated with line items and delivery details copied from the given invoice, using the website associated with the given store.

ParameterDescription
invoicethe invoice to copy line items and delivery details from
storethe e-commerce store whose website the cart is created against

createCartFromInvoice(Invoice invoice, Website website)

Returns: Cart

Creates a pending cart pre-populated with line items and delivery details copied from the given invoice, for the given website. No e-commerce store is associated with the cart.

ParameterDescription
invoicethe invoice to copy line items and delivery details from
websitethe website the cart is created against

createCartFromInvoice(Invoice invoice, Website website, ECommerceStore store)

Returns: Cart

Creates a pending cart for the given website, copying each line item on the invoice to a product order and copying the invoice's delivery address onto the cart.

ParameterDescription
invoicethe invoice whose line items and delivery address are copied
websitethe website the cart is created against
storethe e-commerce store the cart belongs to, may be null

quoteAccepted(Quote quote)

Returns: void

Marks a quote as accepted by delegating to PaymentService, which updates its status and fires a QuoteAcceptedEvent for funnels to react to.

ParameterDescription
quotethe quote being accepted

unAcceptQuote(Quote quote)

Returns: void

Reverts a quote from accepted back to assigned status. Does not fire any funnel events.

ParameterDescription
quotethe quote to un-accept

markQuoteAsNew(Quote quote)

Returns: void

Sets a quote's status back to new. Does not fire any funnel events.

ParameterDescription
quotethe quote to mark as new

quoteRejected(Quote quote)

Returns: void

Marks a quote as rejected and fires a QuoteRejectedEvent for funnels to react to.

ParameterDescription
quotethe quote being rejected

quoteInvoiced(Quote quote)

Returns: void

Marks a quote as invoiced. Does not fire any funnel events.

ParameterDescription
quotethe quote that has been invoiced

quoteSent(Quote quote)

Returns: void

Marks a quote as sent, stored internally as the ASSIGNED status, and fires a QuoteSentEvent for funnels to react to.

ParameterDescription
quotethe quote being sent

cloneQuote(Quote quote, String number)

Returns: Quote

Duplicates a quote under a new number, appending " Copy" to its title, and adds the new quote to any proposal that already contains the original quote.

ParameterDescription
quotethe quote to duplicate
numberthe number to assign to the new quote

cloneInvoice(Invoice invoice, String number, Date dueDate)

Returns: Invoice

Duplicates an invoice under a new number and due date, appending " Copy" to its title.

ParameterDescription
invoicethe invoice to duplicate
numberthe number to assign to the new invoice
dueDatethe due date for the new invoice

clonePurchaseOrder(PurchaseOrder purchaseOrder, String number, Date issuedDate)

Returns: PurchaseOrder

Duplicates a purchase order under a new number and issued date, appending " Copy" to its title.

ParameterDescription
purchaseOrderthe purchase order to duplicate
numberthe number to assign to the new purchase order
issuedDatethe issued date for the new purchase order

deletePaymentItemList(Long id)

Returns: void

Looks up a payment item list (invoice, quote or purchase order) by id and deletes it, if found.

ParameterDescription
idthe id of the payment item list to delete

deletePaymentItemList(PaymentItemList item)

Returns: void

Deletes the given payment item list (invoice, quote or purchase order).

ParameterDescription
itemthe payment item list to delete

deleteProposal(Proposal item)

Returns: void

Deletes a proposal, unlinking it from any quotes it references.

ParameterDescription
itemthe proposal to delete

getProposalById(Long id)

Returns: Proposal

Looks up a proposal by id within the current tenant organisation.

ParameterDescription
idthe id of the proposal to find

getInvoiceListStatus(String name)

Returns: InvoiceListStatus

Resolves an InvoiceListStatus enum value from its string name.

ParameterDescription
namethe name of the status to resolve

newInvoiceBean()

Returns: InvoiceBean

Creates a new, empty InvoiceBean for building up an invoice before calling createInvoice.

newLineItemBean()

Returns: PaymentLineItemBean

Creates a new, empty PaymentLineItemBean for building up a line item.

getNextInvoiceNumber()

Returns: String

Generates the next available invoice number, retrying past any number already in use. This performs a database lookup and is not a cheap accessor despite its name.

getNextQuoteNumber()

Returns: String

Generates the next available quote number, retrying past any number already in use. This performs a database lookup and is not a cheap accessor despite its name.

getNextPurchaseOrderNumber()

Returns: String

Generates the next available purchase order number, retrying past any number already in use. This performs a database lookup and is not a cheap accessor despite its name.

getPaymentItemList(Long id)

Returns: PaymentItemList

Looks up a payment item list (invoice, quote or purchase order) by id within the current tenant organisation.

ParameterDescription
idthe id of the payment item list to find

addAttachmentToPaymentItemList(PaymentItemList paymentItemList, String fileName, String hash, String contentType)

Returns: void

Attaches an already-uploaded file to a payment item list.

ParameterDescription
paymentItemListthe payment item list to attach the file to
fileNamethe display file name of the attachment
hashthe content hash identifying the uploaded file in the blob store
contentTypethe MIME type of the attachment

deleteAttachmentToPaymentItemList(PaymentItemList paymentItemList, String hash)

Returns: void

Removes an attachment from a payment item list, identified by its content hash.

ParameterDescription
paymentItemListthe payment item list to remove the attachment from
hashthe content hash identifying the attachment to remove

getInvoice(Long id)

Returns: Invoice

Looks up an invoice by id within the current tenant organisation.

ParameterDescription
idthe id of the invoice to find

getInvoiceAsPDF(Invoice invoice)

Returns: String

Renders an invoice to PDF and uploads the resulting file to the VFS, returning its content hash.

ParameterDescription
invoicethe invoice to render

getPurchaseOrderAsPDF(PurchaseOrder purchaseOrder)

Returns: String

Renders a purchase order to PDF and uploads the resulting file to the VFS, returning its content hash.

ParameterDescription
purchaseOrderthe purchase order to render

createInvoice(BaseEntity customer, BaseEntity vendor, InvoiceBean invoiceList)

Returns: Invoice

Creates and saves a new invoice for the given customer and vendor, using the field values in the given bean.

ParameterDescription
customerthe customer the invoice is issued to, may be null
vendorthe vendor issuing the invoice, may be null
invoiceListthe bean holding the invoice's field values

createInvoice(InvoiceBean invoiceList)

Returns: Invoice

Creates and saves a new invoice with no customer or vendor set, assigning it the next available invoice number if the bean does not already specify one.

ParameterDescription
invoiceListthe bean holding the invoice's field values

createQuote(String number, String title, String description, Date expiryDate, BaseEntity customer, BaseEntity vendor)

Returns: Quote

Creates a quote with no associated lead or proposal. See the overload that accepts a lead and proposal for further details.

ParameterDescription
numberthe quote number, or null/blank to assign the next available number
titlethe title of the quote
descriptionthe description of the quote
expiryDatethe date the quote expires
customerthe customer the quote is issued to
vendorthe vendor issuing the quote

createQuote(String number, String title, String description, Date expiryDate, BaseEntity customer, BaseEntity vendor, Lead lead, Proposal proposal)

Returns: Quote

Creates and saves a new quote, assigning it the next available quote number if none is given.

ParameterDescription
numberthe quote number, or null/blank to assign the next available number
titlethe title of the quote
descriptionthe description of the quote
expiryDatethe date the quote expires
customerthe customer the quote is issued to
vendorthe vendor issuing the quote
leadthe lead this quote is associated with, may be null
proposalthe proposal this quote is added to, may be null

getQuoteAsPDF(Quote quote)

Returns: String

Renders a quote to PDF and uploads the resulting file to the VFS, returning its content hash.

ParameterDescription
quotethe quote to render

addLineItem(PaymentItemList paymentItemList, String description, BigDecimal quantity, BigDecimal unitPrice, String account, BigDecimal taxRate, BigDecimal amount, BigDecimal discountRate, ProductSku productSku, BaseEntity supplier)

Returns: LineItem

Adds a new line item to a payment item list (invoice, quote or purchase order) and notifies the payment service so totals are recalculated.

ParameterDescription
paymentItemListthe invoice, quote or purchase order to add the line item to
descriptionthe description of the line item
quantitythe quantity ordered
unitPricethe price per unit, excluding tax
accountthe account code the line item is recorded against
taxRatethe tax rate expressed as a percentage, for example 20% is expressed as 20, not 0.20
amountthe line total
discountRatethe discount rate expressed as a percentage
productSkuthe product sku the line item is for, may be null
supplierthe supplier of the product, may be null

addLineItem(PaymentItemList paymentItemList, CheckoutLineItem checkoutLineItem)

Returns: LineItem

Adds a line item to a payment item list, copying its values from a checkout line item. The checkout tax rate is stored as a fraction (for example 10% is 0.1), so it is converted to a percentage before being stored on the line item.

ParameterDescription
paymentItemListthe invoice, quote or purchase order to add the line item to
checkoutLineItemthe checkout line item to copy values from

deleteLineItem(PaymentItemList paymentItemList, LineItem lineItem)

Returns: void

Removes a line item from a payment item list. Does nothing if either argument is null.

ParameterDescription
paymentItemListthe invoice, quote or purchase order to remove the line item from
lineItemthe line item to remove

updateLineItem(PaymentItemList paymentItemList, LineItem lineItem)

Returns: void

Saves changes made to a line item already belonging to a payment item list. Does nothing if either argument is null.

ParameterDescription
paymentItemListthe invoice, quote or purchase order the line item belongs to
lineItemthe line item to save

findLineItemsByProductSku(ProductSku productSku)

Returns: List<LineItem>

Finds all line items in the current tenant organisation that reference the given product sku.

ParameterDescription
productSkuthe product sku to search for

markInvoiceAsDraft(Invoice invoice)

Returns: void

Sets an invoice's status to draft and saves it.

ParameterDescription
invoicethe invoice to update

markInvoiceAsSent(Invoice invoice)

Returns: void

Sets an invoice's status to sent and saves it.

ParameterDescription
invoicethe invoice to update

markInvoiceAsPaid(Invoice invoice)

Returns: void

Sets an invoice's status to paid and saves it.

ParameterDescription
invoicethe invoice to update

markInvoiceAsOverdue(Invoice invoice)

Returns: void

Sets an invoice's status to overdue and saves it.

ParameterDescription
invoicethe invoice to update

findInvoiceByNumber(String number)

Returns: Invoice

Looks up an invoice by its number within the current tenant organisation.

ParameterDescription
numberthe invoice number to search for

findQuoteByNumber(String number)

Returns: Quote

Looks up a quote by its number within the current tenant organisation.

ParameterDescription
numberthe quote number to search for

findPurchaseOrderByNumber(String number)

Returns: PurchaseOrder

Looks up a purchase order by its number within the current tenant organisation.

ParameterDescription
numberthe purchase order number to search for

newPaymentTransaction(Profile createdBy, String paymentProviderAppId)

Returns: PaymentTransaction

Creates a blank payment transaction for the current website with only its minimal properties set. The calling code must set any further properties and save it.

ParameterDescription
createdBythe profile the transaction is created by
paymentProviderAppIdthe id of the payment provider app the transaction is processed through

createRecurringTransaction(PaymentTransaction ptx, String customerTokenId, BigDecimal amount, String currencyCode, Date startDate, Frequency frequency, int multiples, String invoiceNumExp, String invoiceDescExpr, Cart cart)

Returns: RecurringTransaction

Creates and saves a recurring transaction against a payment transaction, defining how often and how many times it repeats.

ParameterDescription
ptxthe payment transaction the recurring transaction is created against
customerTokenIdthe payment provider's stored token id for the customer
amountthe amount charged on each repeat
currencyCodethe currency the amount is charged in
startDatethe date the first repeat is due
frequencyhow often the transaction repeats
multiplesthe number of times the transaction repeats
invoiceNumExpan expression used to generate the invoice number for each repeat
invoiceDescExpran expression used to generate the invoice description for each repeat
cartthe cart the recurring transaction is associated with

createRecurringTransactionResult(RecurringTransaction rtx, PaymentTransaction ptx)

Returns: RecurringTransactionResult

Records the completion of one repeat of a recurring transaction, linking it to the payment transaction that processed it.

ParameterDescription
rtxthe recurring transaction the result belongs to
ptxthe payment transaction that processed this repeat

findRecurringTransaction(long id)

Returns: RecurringTransaction

Looks up a recurring transaction by id within the current tenant organisation.

ParameterDescription
idthe id of the recurring transaction to find

lookupFrequency(String ru)

Returns: Frequency

Resolves a recurring transaction Frequency from the string form of a RepeatUnit (one of d, m, w or y).

ParameterDescription
ruthe repeat unit name to resolve

lookupFrequency(RepeatUnit ru)

Returns: Frequency

Resolves a recurring transaction Frequency from a RepeatUnit. Throws a RuntimeException if the repeat unit is not recognised.

ParameterDescription
ruthe repeat unit to resolve

lookupStatus(String status)

Returns: Status

Resolves a RecurringTransaction.Status enum value from its string name.

ParameterDescription
statusthe name of the status to resolve

findPaymentTransactionsForCart(Cart cart)

Returns: List<PaymentTransaction>

Finds all payment transactions recorded against a cart.

ParameterDescription
cartthe cart to search for, may be null

findInvoicesForCart(Cart cart)

Returns: List<PaymentItemList>

Finds all payment item lists (invoices, quotes or purchase orders) recorded against a cart.

ParameterDescription
cartthe cart to search for, may be null

findPaymentTx(long id)

Returns: PaymentTransaction

Looks up a payment transaction by id within the current tenant organisation.

ParameterDescription
idthe id of the payment transaction to find

findRecurringTxForPaymentTx(PaymentTransaction ptx)

Returns: RecurringTransaction

Finds the recurring transaction that a payment transaction was generated for, if any.

ParameterDescription
ptxthe payment transaction to look up, may be null

makeEWayTokenPayment(RecurringTransaction rtx, CredentialsBean credentialsBean)

Returns: PaymentTransaction

Legacy path for submitting a token payment through the old EWayService.

ParameterDescription
rtxthe recurring transaction to charge
credentialsBeanthe eWAY account credentials to use

newCredentialsBean(String user, String password, boolean sandbox)

Returns: CredentialsBean

Creates an eWAY CredentialsBean for the given account.

ParameterDescription
userthe eWAY account username
passwordthe eWAY account password
sandboxtrue to use the eWAY sandbox environment, false for production

resetDueTransaction(DueTransaction dtx)

Returns: void

Clears a due transaction so it is processed again as if it were new, without deleting any related payment transaction or recurring transaction result records, then enqueues a job to reprocess it. Does not start its own transaction, so callers must wrap this call with runInTransaction.

ParameterDescription
dtxthe due transaction to reset

doRecurringPayment(DueTransaction dtx)

Returns: void

Attempts to process one due transaction of a recurring payment: looks up the payment provider app, submits the charge, updates the due transaction's state to complete or failed, and processes any related products on success. Always fires a payment event in a finally block, even if the attempt fails.

ParameterDescription
dtxthe due transaction to process

findProposals(Lead lead)

Returns: ProposalsList

Finds all proposals associated with a lead.

ParameterDescription
leadthe lead to search for

createProposal(Profile customer, List<Quote> quotes)

Returns: Proposal

Creates and saves a new proposal for a customer, containing the given quotes, with status CREATED.

ParameterDescription
customerthe customer the proposal is for
quotesthe quotes included in the proposal

extraFields()

Returns: List<ExtraField>

Returns the extra fields configured for payment item lists in the current tenant organisation, sorted by their configured ordering.

saveExtraFields(PaymentItemList pil, FormContext fc)

Returns: void

Reads each configured extra field's value from the submitted form and saves the ones that were provided onto the payment item list.

ParameterDescription
pilthe payment item list to update
fcthe form context to read submitted extra field values from

saveExtraFields(PaymentItemList pil, Map<String,String> valuesMap)

Returns: void

Saves extra field values onto a payment item list from a map keyed by field name.

ParameterDescription
pilthe payment item list to update
valuesMapthe extra field values to save, keyed by field name

extraFieldValues(PaymentItemList pil)

Returns: Map<String,String>

Reads the currently saved extra field values from a payment item list.

ParameterDescription
pilthe payment item list to read from, may be null

updatePaymentItemList(PaymentItemList pil)

Returns: void

Saves a payment item list and notifies the payment service that it has been updated.

ParameterDescription
pilthe payment item list to update

revisePrices(PaymentItemList pil)

Returns: void

Recalculates the prices on a payment item list's line items.

ParameterDescription
pilthe payment item list to revise

findQuote(long quoteId)

Returns: Quote

Looks up a quote by id within the current tenant organisation.

ParameterDescription
quoteIdthe id of the quote to find

findQuoteStatusType(String status)

Returns: QuoteStatus

Resolves a Quote.QuoteStatus enum value from its string name.

ParameterDescription
statusthe name of the status to resolve

findInvoicePayment(Long id)

Returns: InvoicePayment

Looks up an invoice payment by id within the current tenant organisation.

ParameterDescription
idthe id of the invoice payment to find

findInvoicePayment(PointsDebit pointsDebit)

Returns: InvoicePayment

Looks up the invoice payment created for a points debit, within the current tenant organisation.

ParameterDescription
pointsDebitthe points debit to look up the invoice payment for

Returns: List<InvoicePaymentLink>

Finds all invoice payment links recorded against an invoice.

ParameterDescription
invoicethe invoice to search for

Returns: List<InvoicePaymentLink>

Finds all invoice payment links recorded against an invoice payment.

ParameterDescription
invoicePaymentthe invoice payment to search for

Returns: void

Deletes an invoice payment link, looked up by its owning invoice payment and its own id, if found.

ParameterDescription
invoicePaymentthe invoice payment the link belongs to
idthe id of the invoice payment link to delete

deleteInvoicePayment(InvoicePayment invoicePayment)

Returns: void

Deletes an invoice payment, if not null.

ParameterDescription
invoicePaymentthe invoice payment to delete

newInvoicePaymentBuilder()

Returns: InvoicePaymentBuilder

Creates a new InvoicePaymentBuilder for the current tenant organisation. Set properties on the builder and then call build() to create and save an InvoicePayment.

createPurchaseOrder(String number, String title, String description, Date issuedDate, BaseEntity customer, BaseEntity vendor, PurchaseOrderBean purchaseOrderList)

Returns: PurchaseOrder

Creates and saves a new purchase order for the given customer and vendor, using the field values in the given bean.

ParameterDescription
numberthe purchase order number
titlethe title of the purchase order
descriptionthe description of the purchase order
issuedDatethe date the purchase order is issued
customerthe customer the purchase order is issued to
vendorthe vendor the purchase order is issued by
purchaseOrderListthe bean holding the purchase order's field values
To get full access to the Kademi Hub existing customers can login here, or new customers can register here.