<ul><li><p>www.jBilling.com</p><p>TheOpenSourceEnterpriseBillingSystem</p><p>EnterpriseEdition3.2IntegrationGuide</p><p>Thisversionpublished:29.08.13</p><p>DocumentRevisionNo.:1.5</p><p>Copyright2013EnterprisejBillingSoftwareLtd 1</p></li><li><p>jBillingIntegrationGuide</p><p>Introduction </p><p>ThankyouforyourinterestinjBilling!</p><p>In this document, we will explore in detail the integration features of jBilling that help external applications to connect with the billing infrastructure provided by jBilling and perform seamless interaction.</p><p>jBilling provides a comprehensive set of GUI enabled features for viewing, managing, and keeping track of all billing and invoicing operations for your organization. Along with its core functionality, jBilling provides a rich integration layer that enables your applications to tightly interact with the billing infrastructure and streamline all billingrelated operations into your organization'sworkflow.</p><p>This document contains valuable information for application developers and architects what want to integrate jBilling with their own systems, or perform actions in jBilling from external applications. Here, you'll find a comprehensive reference to the jBilling Web Services APIs and an introductory examples including the glue code that explains how many of these integration taskscanbeaccomplished.</p><p>TheNeedforIntegrationApplicationsneedtointerfacewithotherapplications.Moreso,forabillingapplicationthatcontainssignificantinformationaboutthingslikeCustomerStatus,PaymentsOverdue,SubscriptionsforCustomeretc.Thisinformationislikelytobeimportantinputsfordecisionmakinginotherbusinessapplicationsandprocesses.Aselfcontainedbillingapplication,ontheotherhand,hasanotherbigdrawback:tokeepitupdated,youwouldneeda</p><p>Copyright2013EnterprisejBillingSoftwareLtd 2</p></li><li><p>separatedataentryprocessthatfeedsthebillingdatafromyoursystemintothebillingapplication.Thisisbothtimeandresourceconsuming.Forexample:</p><p>Let's suppose you own a website with a member's area. In order to access the member area, the customer would need to pay a monthly fee. If the billing data is kept separately, when a new user subscribes to the website, the billing data would need to wait until somebody enters data into the billing application, and after the payment is cleared the same person would need to updatethewebsiteinordertograntaccesstotheuser.</p><p>The manual authorization process would have a heavy impact on the site's functionality. Even if there are instant payment options, such as credit cards, the user would have to wait for a manualoperationtotakeplacebeforebeinggrantedaccesstotheservicehepaidfor.</p><p>jBilling solves this problem by rendering common billing and data retrieval operations available to your system via service calls. With a relatively small programming effort, you can integrate the billing application with your own systems or business processes, so that when the new user signs in, you can instantly pass the data to the billing application, have the payment cleared and grantaccesswithouttheneedformanualoperations.</p><p>As we'll see in the following sections, integration services in jBilling are almost as comprehensive as the billing functionality provided through the standard web interface. Using the integration layer, you can retrieve lots of useful data from jBilling, as well as create, update or deleteUsers,Items,OrdersandInvoices.</p><p>jBillingIntegrationRequirementsjBillingprovidesits'integration'servicesinthreedistinctflavors:</p><p>1. SOAP(SimpleObjectAccessProtocol)2. Hessian/Burlap(lightweightwebserviceprotocols)3. SpringHTTPInvoker</p><p>In order to fully acquire, and take advantage of, the information contained herein, you may need tohaveatleastabasicgraspofwhatSOAPisandhowitworks.</p><p>TolearnaboutHessianandBurlap,visittheirhomepageathttp://hessian.caucho.com</p><p>SOAP is a XMLbased 'programming language independent' protocol for exchanging information over HTTP. Therefore, it enables diverse platforms to communicate without bias. Since jBilling implements its services through SOAP, even business applications running on nonJava platformscancommunicatetoorintegratewithjBillingbecauseofitsSOAPsupport.</p><p>Hessian is a fast binary web services protocol that works over HTTP, with implementations available in a number of languages. Like SOAP, it has the advantages of being firewall friendly and the ability to make use of authentication and encryption, yet it is similar in speed and </p><p>Copyright2013EnterprisejBillingSoftwareLtd 3</p></li><li><p>bandwidth performance to Java RMI. Hessian 2 provides even much better performance as compared to its previous version. Burlap is closely related to Hessian except that it uses human readable XML instead of binary messages. However, neither Hessian nor Burlap require an externallydefinedWSDLfile,whichisrequiredbySOAP.</p><p>Most examples provided in this document are explained in Java, therefore, some knowledge of Java programming language would prove very useful. There is still a small section dedicated to implementing jBilling integration in other languages such as C#.NET and PHP. Please refer to your language/platform's documentation in order to determine what specific SOAP support it provides, and how to make use of it (specifically, how to call remote SOAP services, and how to passparametersanddecodethereturnedvalues).</p><p>It is also recommended that you have a basic understanding of jBilling's functionality and usage. You can find this information in other documents available from jBilling User Guide and Getting Started. Knowing how the program works is of course necessary to understand the scope and usage of each service call. Last but not least, you will need a running copy of jBilling in order to execute the examples contained in this document. Following the Trend tutorial on the Getting Started document is also necessary to generate some of the data required for the examplestowork.</p><p>PreparingjBillingforIntegration</p><p>ConfiguringandUsingaRemotingMethod</p><p>ConfigurationYou can make use of the jBilling API in any java application by including the jbilling.jar and jbillingremotebeans.xmlfiles in your classpath. Both of these artifacts can be found in the jbilling/resources/api/folder that was packaged with the binary jBilling distribution.</p><p>The jbillingremotebeans.xmlfile contains the Spring configuration for accessing the jBilling remote webservices API using the JbillingAPIFactory and JbillingAPI classes. This file contains three different Spring bean configurations, one for each of the 3 supported webservice protocols available in jBilling outofthebox. jBilling comes preconfiguredwith:</p><p> Hessian/Burlap(beanname'apiClient') SOAP(beanname'apiClient2') SpringHTTPInvoker(beanname'_apiClient3')</p><p>Copyright2013EnterprisejBillingSoftwareLtd 4</p></li><li><p>These Spring beans connect to the exposed webservices in jBilling and provide access to the jBilling integration services. Unlike the others, the Spring HTTP Invoker protocol is an unauthenticated protocol. If you wish to use Spring HTTP Invoker for integration you'll need to configure an alternate authentication filter that forces the credentials to be used when making nonauthenticated API calls. See the section Enabling/Disabling authentication for jBilling webservicessectionbelowforinformationregardingthis.</p><p>Copyright2013EnterprisejBillingSoftwareLtd 5</p></li><li><p>SecuringIntegrationAccess</p><p>OverviewWhile integration services could be an extremely useful feature, they do bring up some security concerns you'll need to take into account. It is critical that the services are not exposed to external parties, otherwise it could be possible for them to invoke the same functionality you're using(and,mostprobably,youdon'twantanoutsidertobeabletocreateapaymentorinvoice).</p><p>Therefore, the integration services should be exposed only to properly authorized parties. This is, at least in part, guaranteed by jBilling, since by default it requires a client application to identify itself via a user name/password pair, before servicing any of its requests. It would also be important to transmit all data over a secure channel, which can be accomplished by using the SOAPorHessian/BurlapcallsoveranSSLtunnel,somethingwe'llcovershortly.</p><p>Ideally, the web services would be exposed only to the server(s) that require it, and any other parties should be excluded. This can be accomplished by using a firewall application that limits the IP addresses that have access to jBilling's integration services. Please refer to the documentation of the Operating System or platform in which your copy of jBilling is to run, in </p><p>Copyright2013EnterprisejBillingSoftwareLtd 6</p></li><li><p>ordertohavesomeinformationonhowtorestrictaccesstospecificTCPportsinyoursystem.</p><p>It is also recommended that all service calls are performed by means of an encrypted channel, as provided by the SSL (Secure Socket Layer) protocol. This effectively avoids any threats related to unauthorized interception or decryption of the service calls. SSL also ensures that the party you're engaging communication with is actually your intended recipient, nullifying any impersonationattempts.</p><p>In order to determine if the party engaged in communication is actually who it is pretending to be, SSL uses certificates. Therefore, in order to establish an SSL connection to jBilling, it could be requiredtohaveacopyofjBilling'scertificateinyourdevelopmentandproductionsystems.</p><p>RestrictingAccesstoKnownIPAddressesBy default, jBilling will accept webservice calls from any IP address. You can change this behaviour to restrict API client requests to known machines within your own network. To change this, edit the jbilling/jbillingConfig.groovy script and uncomment the grails.plugins.springsecurity.ipRestrictionsproperty.</p><p>IP restriction patterns can be provided as singlevalue strings, or a multivalue list of strings. TheycanalsouseCIDRmasks,andcanspecifyeitherIPv4orIPV6patterns.</p><p>grails.plugins.springsecurity.ipRestrictions=['/services/**':'192.168.0.110','/hessian/**':['192.168.0.110','192.168.0.111'],'/httpinvoker/**':'192.168.0.0/24']</p><p>NotethatyoucanalwaysaccesstheseURLsfromlocalhost,regardlessoftheIPrestriction.</p><p>Enabling/DisablingauthenticationforjBillingwebservicesBy default, all calls to jBilling must be authenticated. In most cases, this is the desired behavior. If Spring HTTP Invoker is used to make calls to jBilling, authentication is not available. If the jBilling server is called by clients within an internal network secured from outside access, it may alsobepreferabletoremovetheneedtoforceclientstoauthenticatethemselves.</p><p>You can force any exposed webservice to use a specific set of credentials (instead of asking for authentication) by editing the jbilling/jbillingConfig.groovyscript. Find the grails.plugins.springsecurity.filterChain.chainMapproperty and change the authentication filter set to ignore the default JOINED_FILTERS, and instead use a filter chain that contains the staticAuthenticationProcessingFilter(copy the filter chain used for'/httpinvoker/'):</p><p>grails.plugins.springsecurity.filterChain.chainMap=['/services/**':'JOINED_FILTERS,exceptionTranslationFilter','/hessian/**':'JOINED_FILTERS,exceptionTranslationFilter',</p><p>Copyright2013EnterprisejBillingSoftwareLtd 7</p></li><li><p>'/httpinvoker/**': 'securityContextPersistenceFilter,staticAuthenticationProcessingFilter,securityContextHolderAwareRequestFilter,basicExceptionTranslationFilter,filterInvocationInterceptor',</p><p>'/**': 'JOINED_FILTERS,basicAuthenticationFilter,basicExceptionTranslationFilter']</p><p>The staticAuthenticationProcessingFilter itself is configured in the jBilling resources.groovyfile. You'll need to recompile jBilling to access this configuration file so youcanchangethestaticauthenticationcredentials.</p><p>Enabling/DisablingcompanysecuritychecksIf only one company is using the jBilling installation, unnecessary security checks, which make sure one company is not accessing another company's data, can be disabled to further increase performance.Todisablethecheck,editthefollowingfile:</p><p>./grailsapp/conf/spring/resources.xml</p><p>Comment out or delete the two XML beans under the section AOP: Security / Logging: Bean idswebServicesSecurityAdviceandwebServicesSecurityAdvisor).</p><p>SettingupjBillingtoacceptexternalcallsAs mentioned earlier, jBilling will not accept all external calls it gets, but will require the caller to identify itself with a user name and password in order to service the request. Otherwise, the request will receive an error in response. This is a simple but effective measure that improves overall security. Of course, this also means you (or the system administrator) will need to set up anaccountinjBillingthatwillbeauthorizedtoperformexternalcalls.</p><p>Once you've followed the Getting Started tutorial and created the initial billing entity, the user name and password you entered in the entity setup screen will represent the user name and password of jBilling's administrator account. You can grant access to this administrator account (or any other account you create for this purpose) to connect remotely and perform service calls.</p><p>In order to do so, you'll need to login as the administrator and give an account the 'Web Service APIaccess'permissiontoallowtheaccounttobeusedtoauthenticatewebserviceaccess.</p><p>You can do this from either the Roles configuration screen (Configuration &gt; Roles) to grant access to an entire group of users, or by editing the individual user permissions (Configuration &gt;Users&gt;Permissions).</p><p>Copyright2013EnterprisejBillingSoftwareLtd 8</p></li><li><p>AuthenticatingaWebServiceclientSOAP, Hessian and Burlap all use HTTP Basic authentication to gain access to the jBilling webservice endpoint. All web service clients must authenticate themselves so that jBilling can enforcerestrictionsondataaccessandpreventunauthorizedaccesstointegrationservices.</p><p>The user name string must contain both the login name..</p></li></ul>