Many payment gateways support recurring billing and provide interfaces to create and manage subscriptions. KonaKart includes a recurring billing implementation for AuthorizeNet in the file called AdminPayment.java in the KonaKart\custom\modules\src\com\konakartadmin\modules\payment\authorizenet directory. This file contains methods to create, update and cancel an AuthorizeNet subscription as well as a method to read the status of a subscription in order to determine whether it is active or has been cancelled etc. The file also contains a method to perform a standard credit card payment through AuthorizeNet which could be used when the recurring billing is managed by KonaKart rather than the payment gateway. In order to create something similar for other payment gateways, this file should be copied into the relevant directory (e.g. KonaKart\custom\modules\src\com\konakartadmin\modules\payment\myGateway) and customized in order to implement the protocol of the chosen gateway.
The way to call these payment gateway methods is through the Admin Engine which contains a method to call a payment gateway called:
public NameValue[] callPaymentModule(String sessionId, String moduleClassName, PaymentOptions options) throws KKAdminException;
The PaymentOptions object contains data to configure the method and the moduleClassName is the actual name of the class that is instantiated.
In order to manage a recurring billing subscription the steps are:
A subscription must be inserted into the KonaKart database and also sent to the payment gateway since it is the payment gateway that will actually perform the billing. The trigger for this operation is when a customer confirms an order in the storefront application. The storefront code must create a subscription which is saved in the KonaKart database. An example can be found in the file AuthorizenetAction.java under the directory KonaKart\custom\modules\src\com\konakart\actions\gateways. The method (which is commented out) is called manageRecurringBilling() . A Subscription object is created and inserted into the KonaKart database using the insertSubscription() API call . In order to be able to also create a subscription through the payment gateway you can add code to the OrderIntegrationMgr which can be found in the directory KonaKart\custom\appn\src\com\konakart\bl . As you can see, the OrderIntegrationMgr has methods that are called before and after inserting and updating a subscription. The example code can be found in the afterInsertSubscription() method.
/*
* Create a PaymentOptions object to pass to the method that calls the payment gateway.
* The payment module gets the subscription code from the payment gateway and updates
* the subscription in the KonaKart database to add the code.
*/
PaymentOptions options = new PaymentOptions();
options.setSubscriptionId(subscription.getId());
options.setOrderId(subscription.getOrderId());
options.setCreditCard((CreditCard) (subscription.getCreditCard()));
options.setAction(KKConstants.ACTION_CREATE_SUBSCRIPTION);
adEngineMgr.callPaymentModule(getEng().getEngConf(),
"com.konakartadmin.modules.payment.authorizenet.AdminPayment", options);
This code creates a PaymentOptions object, fills it with the relevant ids and credit card information before passing it to the payment module in order to create the subscription.
A subscription may need to be updated for various reasons. Common updates are to modify the amount that is billed at regular intervals and to add new credit card details when the current card expires.
In order to achieve this, the storefront application must gather the new credit card information from the customer and call the updateSubscription() API call in the same way as the insertSubscription() API call was called above. The example call to AuthorizeNet is again in the OrderIntegrationMgr in the method called afterUpdateSubscription() . Here you can see that AuthorizeNet is called to update the subscription.
/*
* Create a PaymentOptions object to pass to the method that calls the payment gateway.
* The payment module gets the subscription code from the subscription object in the
* KonaKart database which it looks up using the id in the PaymentOptions.
*/
PaymentOptions options = new PaymentOptions();
options.setSubscriptionId(subscription.getId());
options.setOrderId(subscription.getOrderId());
options.setCreditCard((CreditCard)(subscription.getCreditCard()));
options.setAction(KKConstants.ACTION_UPDATE_SUBSCRIPTION);
adEngineMgr.callPaymentModule(getEng().getEngConf(),
"com.konakartadmin.modules.payment.authorizenet.AdminPayment", options);
This code creates a PaymentOptions object, fills it with the relevant ids and credit card information before passing it to the payment module in order to update the subscription.
AuthorizeNet allows you to detect the status of a subscription through the API. Using this functionality it's possible to create a batch program that checks the status for all active subscriptions in the KonaKart database in order to detect whether any require attention. If the credit card has expired, an eMail may automatically be sent by the batch program to the customer asking him to log into the store front application and provide new credit card information. Alternatively the payment gateway may generate reports or lists of accounts that require attention.