org.lightningj.paywall.paymenthandler

Interface PaymentHandler

All Known Implementing Classes:

BasePaymentHandler, DemoPaymentHandler, DemoPaymentHandler, SpringPaymentHandler

public interface PaymentHandler

Interface for a PaymentHandler handling orders, invoices and settlements.

All payment flows need a custom implementations of a payment handler persisting generated invoices and constructing orders from an order request constructed from a WebService with PaymentRequired annotation.

It is recommended to implement a class that inherits the BasePaymentHandler that takes care of most of the logic.

Created by Philip Vendil on 2018-12-04.

Method Summary

Modifier and Type	Method and Description
Settlement	checkSettlement(byte[] preImageHash, boolean includeInvoice) Method to check if a given preImageHash is settled and returns a settlement value object if invoice is settled.
Order	createOrder(byte[] preImageHash, OrderRequest orderRequest) Method to create an order from a preImageHash and and order request.
LightningHandlerContext	getLightningHandlerContext() Method to generate the latest LightningHandlerContext of latest known state of the lightning node.
void	init() Method that is called during the startup the application to set up all required sub components of the PaymentHandler.
Invoice	lookupInvoice(byte[] preImageHash) Method to lookup an invoice in the PaymentHandler.
void	markAsExecuted(byte[] preImageHash) Method to flag a related payment flow is a pay per request type and has been processed successfully.
void	registerListener(PaymentListener listener) Method to add the listener to the set of listeners listening on payment events.
Settlement	registerSettledInvoice(Invoice settledInvoice, boolean registerNew, OrderRequest orderRequest, LightningHandlerContext context) Method to manually register an invoice as settled (isSettled must be set to true) used in some payment flows instead of listening on lightningHandler events.
void	unregisterListener(PaymentListener listener) Method to remove the listener to the set of listeners listening on payment events.

Method Detail

init

void init()
   throws InternalErrorException

Method that is called during the startup the application to set up all required sub components of the PaymentHandler.

Throws:

InternalErrorException - if internal error occurred setting up the PaymentHandler.

createOrder

Order createOrder(byte[] preImageHash,
                  OrderRequest orderRequest)
           throws java.io.IOException,
                  InternalErrorException

Method to create an order from a preImageHash and and order request. The implementation should lookup the article id and return an order with all required fields set.

Parameters:

preImageHash - the unique preImageHash used to identify a payment flow withing a lightning payment.

orderRequest - the specification of the order that should be created calculated from data in the PaymentRequired annotation.

Returns:

a newly created order used to create a lightning invoice in LightningHandler.

Throws:

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred creating the order.

lookupInvoice

Invoice lookupInvoice(byte[] preImageHash)
               throws java.io.IOException,
                      InternalErrorException

Method to lookup an invoice in the PaymentHandler. The payment handler might call the LightningHandler to get complementary data about the invoice.

Parameters:

preImageHash - the unique preImageHash used to identify an invoice withing a lightning payment.

Returns:

the related invoice or null if no invoice with related preImageHash found.

Throws:

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred looking up the invoice.

checkSettlement

Settlement checkSettlement(byte[] preImageHash,
                           boolean includeInvoice)
                    throws AlreadyExecutedException,
                           java.lang.IllegalArgumentException,
                           java.io.IOException,
                           InternalErrorException

Method to check if a given preImageHash is settled and returns a settlement value object if invoice is settled.

Parameters:

preImageHash - the preImageHash of the invoice to check.

includeInvoice - if a invoice should be included in the settlement response. This might consume more resources.

Returns:

a settlement value object of related preImageHash if invoice is settled, otherwise null.

Throws:

AlreadyExecutedException - if related payment is pay per request and is already executed.

java.lang.IllegalArgumentException - if related payment is per request and is already executed.

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred looking up the settlement.

registerSettledInvoice

Settlement registerSettledInvoice(Invoice settledInvoice,
                                  boolean registerNew,
                                  OrderRequest orderRequest,
                                  LightningHandlerContext context)
                           throws java.lang.IllegalArgumentException,
                                  java.io.IOException,
                                  InternalErrorException

Method to manually register an invoice as settled (isSettled must be set to true) used in some payment flows instead of listening on lightningHandler events.

Parameters:

settledInvoice - a settled invoice that should be registered in the payment handler.

registerNew - if a new payment data should be created if no prior object existed for related preImageHash.

orderRequest - the specification of the order that should be created calculated from data in the PaymentRequired annotation. Only used if new payment data needs to be registered.

context - the latest known state of the lightning handler. Null if no known state exists.

Returns:

a settlement value object for the given settledInvoice.

Throws:

java.lang.IllegalArgumentException - if settled invoices preImageHash does exists as payment data and registerNew is false.

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred registering a settled invoice.

markAsExecuted

void markAsExecuted(byte[] preImageHash)
             throws java.io.IOException,
                    InternalErrorException

Method to flag a related payment flow is a pay per request type and has been processed successfully.

Parameters:

preImageHash - the preImageHash of the payment to mark as processed.

Throws:

java.io.IOException - if communication exception occurred in underlying components.

InternalErrorException - if internal exception occurred updating the payment or no related payment found.

registerListener

void registerListener(PaymentListener listener)
               throws InternalErrorException

Method to add the listener to the set of listeners listening on payment events.

Parameters:

listener - the listener to register.

Throws:

InternalErrorException - if internal exception occurred registering the listener.

unregisterListener

void unregisterListener(PaymentListener listener)
                 throws InternalErrorException

Method to remove the listener to the set of listeners listening on payment events.

Parameters:

listener - the listener to un-register.

Throws:

InternalErrorException - if internal exception occurred un-registering the listener.

getLightningHandlerContext

LightningHandlerContext getLightningHandlerContext()
                                            throws InternalErrorException

Method to generate the latest LightningHandlerContext of latest known state of the lightning node. Used to make sure the PaymentHandler starts listening on the correct location of the invoice event queue after restart. For LND Nodes should this method return a LNDLightningHandlerContext

Returns:

the last known state of lightning handler context.

Throws:

InternalErrorException - if internal exception occurred fetching latest known state of lightning handler.