JBilling 3.2 Integration Guide

     

 

          The Open Source Enterprise Billing System 

www.jBilling.com 

   

Enterprise Edition 3.2 Integration Guide 

 

This version published: 29.08.13  Document Revision No.: 1.5 

 

   

      Copyright ©2013 Enterprise jBilling Software Ltd

 

     1 

     

jBilling Integration Guide  Introduction

  Thank you for your interest in jBilling!  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.  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  billing­related  operations   into  your  organization's workflow.  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  tasks can be accomplished. 

The Need for Integration  Applications need to interface with other  applications. More so, for a billing  application that contains significant  information about things like Customer  Status, Payments Overdue, Subscriptions  for Customer etc. This information is likely  to be important inputs for decision making  in other business applications and  processes.    A self­contained billing application, on the  other hand, has another big drawback: to  keep it updated, you would need a      Copyright ©2013 Enterprise jBilling Software Ltd

 

     2 

     

separate data­entry process that feeds the billing data from your system into the billing  application. This is both time and resource consuming. For example:  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  update the website in order to grant access to the user.  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  manual operation to take place before being granted access to the service he paid for.  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  grant access without the need for manual operations.  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  delete Users, Items, Orders and Invoices. 

jBilling Integration Requirements  jBilling provides its 'integration' services in three distinct flavors:  1. SOAP (Simple­Object Access Protocol)  2. Hessian/Burlap (lightweight web service protocols)  3. Spring HTTP Invoker  In  order  to  fully   acquire,  and  take  advantage  of,  the  information contained herein, you may  need  to have at least a basic grasp of what SOAP is and how it works.  To learn about Hessian and Burlap, visit their homepage at http://hessian.caucho.com  SOAP  is   a  XML­based  '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  non­Java  platforms can communicate to or integrate with jBilling because of its SOAP support.  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      Copyright ©2013 Enterprise jBilling Software Ltd

 

     3 

     

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  externally defined WSDL file, which is required by SOAP.  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  pass parameters and decode the returned values).  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  examples to work. 

Preparing jBilling for Integration  Configuring and Using a Remoting Method  Configuration  You  can  make  use  of  the  jBilling  API  in  any   java  application  by   including  the  jbilling.jar  and  jbilling­remote­beans.xmlfiles     in  your  class­path.  Both  of  these  artifacts   can  be  found  in  the  jbilling/resources/api/folder     that  was   packaged  with  the  binary   jBilling  distribution.  The  jbilling­remote­beans.xmlfile     contains   the  Spring  configuration  for  accessing  the  jBilling  remote  web­services   API  using  the  JbillingAPIFactory  and  JbillingAPI  classes.  This   file  contains   three  different  Spring  bean  configurations,  one  for  each  of  the  3  supported  web­service  protocols   available  in  jBilling  out­of­the­box.  jBilling  comes   pre­configured with:  ● Hessian/Burlap (bean name " apiClient ")  ● SOAP (bean name " apiClient2 ")  ● Spring HTTP Invoker (bean name "_apiClient3")          Copyright ©2013 Enterprise jBilling Software Ltd

 

     4 

     

                                These  Spring  beans   connect  to  the  exposed  web­services   in  jBilling  and  provide  access  to the  jBilling  integration  services.  Unlike  the  others,  the  Spring  HTTP  Invoker  protocol  is   an  un­authenticated  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  non­authenticated  API  calls.  See  the  section  Enabling/Disabling  authentication  for  jBilling  web services section below for information regarding this. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     5 

     

 

  Securing Integration Access  Overview  While  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, most probably, you don't want an outsider to be able to create a payment or invoice).  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  SOAP or Hessian/Burlap calls over an SSL tunnel, something we'll cover shortly.  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      Copyright ©2013 Enterprise jBilling Software Ltd

 

     6 

     

order to have some information on how to restrict access to specific TCP ports in your system.  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   impersonation attempts.  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  required to have a copy of jBilling's certificate in your development and production systems. 

Restricting Access to Known IP Addresses  By   default,  jBilling  will  accept  web­service  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/jbilling­Config.groovy  script  and  un­comment  the  grails.plugins.springsecurity.ipRestrictions property.  IP  restriction  patterns   can  be  provided  as   single­value  strings,  or  a  multi­value  list  of  strings.  They can also use CIDR masks, and can specify either IPv4 or IPV6 patterns.  grails.plugins.springsecurity.ipRestrictions = [          '/services/**': '192.168.0.110',          '/hessian/**': ['192.168.0.110','192.168.0.111'],          '/httpinvoker/**': '192.168.0.0/24']  Note that you can always access these URLs from localhost, regardless of the IP restriction. 

Enabling/Disabling authentication for jBilling web services  By   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   also be preferable to remove the need to force clients to authenticate themselves.  You  can  force  any   exposed  web­service  to  use  a  specific   set  of  credentials   (instead  of  asking  for  authentication)  by   editing  the  jbilling/jbilling­Config.groovy  script.  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/"):  grails.plugins.springsecurity.filterChain.chainMap = [          '/services/**': 'JOINED_FILTERS,­exceptionTranslationFilter',          '/hessian/**': 'JOINED_FILTERS,­exceptionTranslationFilter',      Copyright ©2013 Enterprise jBilling Software Ltd

 

     7 

     

  '/httpinvoker/**':  'securityContextPersistenceFilter,staticAuthenticationProcessingFilte r,securityContextHolderAwareRequestFilter,basicExceptionTranslationFi lter,filterInvocationInterceptor',    '/**':  'JOINED_FILTERS,­basicAuthenticationFilter,­basicExceptionTranslation Filter'  ]  The  staticAuthenticationProcessingFilter  itself  is   configured  in  the  jBilling  resources.groovyfile.     You'll  need  to  re­compile  jBilling  to  access   this   configuration  file  so  you can change the static authentication credentials. 

Enabling/Disabling company security checks  If  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. To disable the check, edit the following file:  ./grails­app/conf/spring/resources.xml  Comment  out  or  delete  the  two  XML  beans   under  the  section  AOP:  Security  /  Logging:  Bean  ids webServicesSecurityAdvice and webServicesSecurityAdvisor). 

Setting up jBilling to accept external calls  As   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  an account in jBilling that will be authorized to perform external calls.  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.  In  order  to do so, you'll need to log­in as  the administrator and give an account the "Web Service  API access" permission to allow the account to be used to authenticate web­service access.  You  can  do  this   from  either  the  Roles   configuration  screen  (Configuration  >  Roles)  to  grant  access   to  an  entire  group  of users, or by  editing the individual user permissions  (Configuration  > Users > Permissions). 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     8 

     

Authenticating a Web­Service client  SOAP,  Hessian  and  Burlap  all  use  HTTP  Basic   authentication  to  gain  access   to  the  jBilling  web­service  endpoint.  All  web  service  clients   must  authenticate  themselves   so  that  jBilling  can  enforce restrictions on data access and prevent un­authorized access to integration services.  The  user  name  string  must  contain  both  the  login  name  of  the jBilling user attempting to access   AND  the  company   ID  of  the  company   you  are  trying  to  access.  If  you  do  not  provide  the  company ID you will not be able to authenticate your web service client.  Credentials must be provided in the format:  ● user name = "userName;companyId"  ● password = "user's password"  For  example,  you  can  access   the  Trend  web­service  using  the  user  name  "admin;1"  and  the  password "123qwe".  If you are not sure of the ID of your company, look at the ENTITY table in the jBilling database.  SELECT * FROM ENTITY; 

Connecting to jBilling  SOAP  Once  it  is   properly   configured, you'll need to address  all integration calls  to jBilling's  web service  endpoint.  This   endpoint  is   accessible  at  the  same  server  where  jBilling  was   deployed,  in  a  specific URL address, which follows this form:  http://localhost:8080/jbilling/services/api  You  can  query   the  service's   WSDL  (Web  Service  Description  Language)  file.  It  consists   of  an  XML  containing  a  description  of  the  available  service  calls   and  parameters   used  by   each  call,  and  could  be  useful  if  your  programming  platform  provides   a  way   of  automatically   generating  code  for  service  calls   from  a  WSDL,  or  you  have  a  tool  that  can  perform  test  calls   (such  as   SoapUI).  To query the WSDL file, you'll need to append the ?wsdl parameter to the call, for example:  http://localhost:8080/jbilling/services/api?wsdl  Below is a snapshot of the WSDL showing operation getLatestInvoice:        Copyright ©2013 Enterprise jBilling Software Ltd

 

     9 

                                             

Hessian­Burlap  The Hessian service URL is in the following form:  http://localhost:8080/jbilling/hessian/ApiService  Similarly for Burlap:  http://localhost:8080/jbilling/burlap/ApiService 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     10 

     

Spring HTTP Invoker  The Spring HTTP Invoker service URL is in the following form:  http://localhost:8080/jbilling/httpinvoker/ApiService 

Integrating jBilling to your Application  Overview This   section  discusses   the  approaches   available for integrating jBilling in your application. While  jBilling  exposes   a  unique  Web  Services   integration  API,  there  are other ways  of interacting with  that  layer  too,  based  on  the  technology   available  to  the  application  developer  in  the  target  system.  Therefore,  if  your  application  is   written  in  Java  or  at  has  a way  of interfacing with Java, then the  simplest  way   of  integrating  jBilling  with  your  application  is   by   making  use  of  the  +jBilling  Client  API+.  The  +jBilling  client  API+  is   a  pure  Java  API  that  another  Java  program  can  directly   call/use.  Service  calls   can  also  be performed by  means  of plain SOAP or Hessian/Burlap calls. This  type  of  interaction  is   useful  for  those  situations   in  which  you  cannot  use  Java  as   your  programming  language  (either  because  your  server  does   not  support  it  or  because  your  application  has   already been written in another programming language).  Generally,  it  easier  to  use  the  jBilling  API  than  hard­coding  SOAP  or  Hessian/Burlap  calls   directly.  We'll now examine the above possibilities and also see some sample code for each instance. 

The jBilling Client API  The  jBilling  Client  API  is   a  library   that  contains   a  set  of  Java  classes   that  wrap  the  actual  calls   that  are  made  to  jBilling.  This   simplifies   the  interaction with jBilling as  it completely  hides  the low  level  connection  logic,  which  you  would  otherwise  need  to  deal  with  either  directly   or  via a third  party  library  (such as  Axis or CXF). Being Java classes, you must be working in Java or have a  way of invoking Java functions from your programming language.  The  exact same function calls  exposed as  Web Services  are available through the API. It simply   acts as a wrapper.  As   a  sub­project  of  jBilling,  the  jBilling  client  API  has   a  few  extra  advantages.  It  provides   a  standardized  interface  to  jBilling;  so,  even  if  in  the  future  the  SOAP  interfaces   change  or  new      Copyright ©2013 Enterprise jBilling Software Ltd

 

     11 

     

parameters   are  added,  your  code  will  require  little  or  no  modification  at  all  to  adapt  to  those  changes.  Last,  but  not  least,  its   code  is   Open  Source,  so  that  you  can  get  down  to  the  implementation details if needed.  The +jBilling client API+ is well equiped to perform service calls to jBilling in four distinct ways:  1. 2. 3. 4.

By means of standard SOAP calls  Through Hessian calls  Through Burlap calls  Through Spring HTTP Invoker calls 

, of which, you may choose one that best meets your project requirements.  Hessian  generally   has   the  best  features   on  offer:  a  fast  binary   protocol  comparable  in  speed to  Java  RMI  (for  Hessian  2),  HTTP  based for access  through restrictive firewalls, the possibility  of  using  HTTP  authentication  and  SSL  encryption,  and  library   implementations   in  a  number  of  languages.  SOAP still enjoys the best Multi­programming language support. 

The specific calling protocol is hidden in the library's implementation and can be changed to use any one of the above by simply changing a parameter, and by making the required libraries available.

The advantages of using jBilling client API  As   discussed  earlier,  the  +jBilling  Client API+ is  by  far the most convenient means  of integrating  with  jBilling  as   compared  to  handling  SOAP/Hessian  calls   through  custom  programming.  Here  are few additional reasons to support this argument:  First,  the  client  implementation  is   cleanly  separated  from  the  underlying  transport  protocol  used.  Your  code  does   not  change  if  you  switch  from  SOAP calls  to Hessian calls. Also, if other  protocols   are  added  in  the  future,  you'll  be  able  to  use  them  as   needed  without  changing  your  integration code. An example was jBilling 2's introduction of Hessian/Burlap support.  Secondly,  the  API  absorbs   most  of  the  housekeeping  activities  you  need  to  perform  when  using  a  SOAP  library   (such  as  setting up the call parameters  and data types). You will just need  to  instantiate  and  populate  the  correct  data  structures   that  will contain the input and output data,  and call the API to take care of the rest.  Third,  using  this   API  will  allow  you  to  use  advance  deployment  features,  such  as   clustering,  load  balancing  and  fail  over.  Since  the  API  is   a  layer  in  between  the  client  (your  application),  and  the  server  (jBilling),  it  is   the  ideal  place  to  abstract  different  lay­outs   of  the  server  deployment,  keeping  a  simplified  view  from  the  client.  Using  these  features   will  simply   mean  a  change of the API's configuration files, without changing any code.      Copyright ©2013 Enterprise jBilling Software Ltd

 

     12 

     

To  get  an idea of how simple it can be to perform the integration calls, take a look  at the following  code.  The  first  example  calls   jBilling  (using  the  jBilling  client  API)  to  perform  a  simple customer  login sequence (more on this later):  import com.sapienter.jbilling.server.util.api.JbillingAPI;  import com.sapienter.jbilling.server.util.api.JbillingAPIFactory;  import com.sapienter.jbilling.server.user.UserWS;  Integer userId = null;  JbillingAPI api = JbillingAPIFactory.getAPI();  try {  userId = api.getUserId(username);  UserWS userData = api.getUserWS(userId);  } catch (Exception e) {  System.out.println("Invalid  username:  the  user  does  not  exist!");  }  Compare  the  above  code  with  the  following example, which performs  exactly  the same calls  but  using the Apache Axis library:  import javax.xml.namespace.QName;  import javax.xml.rpc.ParameterNode;  import org.apache.axis.client.Call;  import org.apache.axis.client.Service;  import org.apache.axis.encoding.ser.BeanDeserializerFactory;  import org.apache.axis.encoding.ser.BeanSerializerFactory;  Service service = new Service();  Call call = (Call) service.createCall();  call.setTargetEndpointAddress("http://localhost:8080/jbilling/service s/api");  call.setUsername("myusername");  call.setPassword("mypassword");  call.setOperationName("getUserId");  call.setReturnClass(UserWS.class);  QName qn = new QName("http://www.sapienter.com/billing", "UserWS");  BeanSerializerFactory ser1 = new BeanSerializerFactory(  UserWS.class, qn);  BeanDeserializerFactory ser2 = new BeanDeserializerFactory(  UserWS.class, qn);  call.registerTypeMapping(UserWS.class, qn, ser1, ser2); 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     13 

     

try {  Integer userId = call.invoke(new Object[] { username });  UserWS userData = call.invoke(new Object[] { userId });  } catch (Exception e) {  System.out.println("Invalid  username:  the  user  does  not  exist!");  }  Therefore,  a  good  part  of  the  latter  deals   with  the  setup  of  the  Axis   SOAP  calls,  i.e.  more  housekeeping  than  the  actual  logic   of  the  call.  Whereas,  the  jBilling  Client  API  example  works   just as well with Hessian. Simply change an XML file, no coding required.  Take advantage of the Client API. You will probably welcome its simplicity and convenience. 

Using the jBilling Client API  The  Client  API  classes   are  packaged  in  the  jbilling_api.jarfile     that  is   located  in  your  jBilling distribution.  The  API  also  makes   use  of  several  third­party   libraries,  such  as   the  Log4j  and  Commons   Logging  ­  for  logging  infrastructure,  Spring  ­  for  configuration  and  remoting,  Apache  CXF  ­  for  SOAP  API  calls,  and  Hessian  ­  for  Hessian/Burlap  support.  Thus,  you'll  need  the log4j.jar,  commonslogging.jarand     spring.jarfiles     in  your  class   path,  if  your  project  does   not  already include them.  These  files   are  in  the  WEB­INFlib@ directory of the jbillingwebappsbilling.war web  archive, as well.  The  API  also  requires  a  configuration  file,  the  jbillingconfjbilling­remote­beans.xml@  file,  which  needs   to  be  added  to  your  project.  This   file  defines   some  important  parameters   that  the  API  will  later  retrieve  and  use.  More  on  this   in  the  next section.  Depending  on  the  underlying  transport  protocol  you  choose  to  use  (Hessian  or  SOAP),  the  program  will  require  other  libraries.  These  requirements   are  explained  in  detail  in  the  sections   below.  Once  you  have  set  up  your environment for using the jBilling Client API, you can use the  library   by   using  a  factory   method  to  retrieve  an  API  interface,  which  you'll  later use to place the  integration call. You can retrieve an interface to the API in the following manner:  JbillingAPI api = JbillingAPIFactory.getAPI();  The  JbillingAPIobject     allows   you  to  place  integration  calls   directly.  Each  call  performs   a  specific   functionality.  For  example:  api.getUserId()retrieves     the  jBilling  User  ID  of a user,  given  the  user­name.  Obviously,  each  call  requires   different  parameters   and  returns   different  data, according to its use.      Copyright ©2013 Enterprise jBilling Software Ltd

 

     14 

     

The  rest  of  the  API library  contains  classes  that define the parameters  you can use as  input and  receive  as   output  from  the  service  calls.  For  example,  the  com.sapienter.jbilling.server.user.UserWSclass     contains   a  set  of  data  regarding  the  jBilling  user,  such  as  the user name, password, date of creation, etc. As  usual in Java, most  of  these  properties   are  accessible  using  the  getter  and  setter  methods,  such  as   getUsername()or     setPassword().  Most  of  the  integration  effort  goes   into  setting  values   into  these  structures   and  passing  them  to  the  appropriate  service  call.  For  example,  you'll  fill  a  UserWS  structure  and  pass   it  to  the  createUser()service     call.  Most  of  the  API  follows   this   simple logic. 

Configuration  The  jbillingconfjbilling­remote­beans.xml  file  contains   some  fundamental  parameters   that  define  the  connection  to  the  jBilling  server  you  wish  to  communicate  with. This   file is required by the jBilling API library for all connection alternatives.  Each  connection  option  is   contained  within  XML  bean  configuration  tag  with  id="apiClient"  as   an  attribute.  There  are  four  example  configuration  beans,  one  for  each  of  the  four  different  remoting  protocols.  Only   one  bean  should  be  enabled/uncommented  at any  given time, which is   the  configuration  the  API  will  use.  The  note/comment  above each bean indicates  which protocol  it  configures.  Common  properties   to  the  SOAP,  Hessian  and  Burlap  protocols:  username  and  password.  these  values   must  correspond  to  a  valid  account  in  jbilling  that  has   been  granted  permission  to  execute  web service calls. Properties  and setup specific  to each remoting method  are detailed in the sections below. 

The SOAP (CXF) Web Services Method  When  using  this   protocol for service calls  from the jBilling Client API, you will need to include the  CXF  library   (cxf.jar),  which  provides   support  for  SOAP.  A  few  support  libraries   are  also  required:  XmlSchema.jar,  wsdl4j.jar,  FastInfoset.jar  and  neethi.jar  You  can  find  all  the  required  .jar  files   in  your  jBilling  distribution,  in  the  WEB­INFlib@ directory of the  jbillingwebappsbilling.war@  web  archive.  All  these  libraries   will  need  to  be  added  to  your  application's class path in order to be usable by the API.  While  SOAP  is   a  solid  way   of  communicating  with  remote  applications,  it  requires  the parties  to  exchange  XML  files   when  the  service  call  takes   place.  These  files   can be quite massive, and a  great  deal  of  time  is   wasted  in  serializing  parameters   into  an  XML,  and  deserializing  the  response.  For  this   reason,  SOAP  is   relatively   inefficient  when  it  comes   to  implementing  fast  service  calls.  Therefore,  you're  advised  to  use  Hessian  or  Spring  HTTP  Invoker  service, since  they are much faster. 

Properties  ● address   ­  This   is   the  URL  that  points   to  the  jbilling  Web  Services   endpoint  (as       Copyright ©2013 Enterprise jBilling Software Ltd

 

     15 

     

discussed  in  the  Connecting  to  jBilling  section  of  the  Preparing  jBilling  for  Integration  chapter  of  this   document).  As   a  part  of  this   property,  you  may   specify   the  correct  protocol  (either  http  or  https)  and  the  port  number,  if  it  differs   from the standard  port (which is 80 for HTTP and 443 for HTTPS).  For example:  address="http://localhost:8080/jbilling/services/api" 

The Hessian/Burlap Method  The  Hessian  and  Burlap  versions   of  the  Client  API provides  a different communication protocol.  Hessian  messaging  is   in  binary   format  and  therefore  provides   faster  calls,  whereas   Burlap  allows   XML  messages   to  be  used  in  the  cases   where  human  readability   is   needed.  If  using  Hessian  or  Burlap,  hessian.jar  is   required,  and  can  be  found  in  the  WEBINFlib@  directory of the jbillingwebappsbilling.war@ web archive. 

Properties  ● serviceUrl  ­  This   is   the  Hessian  Service  Url  that  jBilling  exposes   (as   discussed  in  Connecting to jBilling section of the Preparing jBilling for Integration  chapter of this document)    ● serviceInterface ­ This is the business interface that exposes the business functionality    ● hessian2  ­  This   is   a  true/false  Hessian  specific   property.  It  indicates   whether  Hessian  should use the newer version 2 protocol, which is faster than version 1.  Although  Hessian  2  is   still  a  draft  specification,  a  value  of  true  is   generally   recommended  for  performance 

Spring HTTP Invoker Method  Spring  HTTP  Invokers   provide  a  powerful mechanism of remote component communication. On  the  server  side,  services   are  exposed  on  top  of  Spring's   infrastructure,  using  the  Spring  bean  configuration  mechanism.  On  the  client  side,  Spring  provides   proxy   capabilities   that  allow  access   to  HTTP  Invoker  exposed services  via a business  interface. Since it is  unauthenticated,  you  must  configure  an  alternate  authentication  filter  that  sets   the  credentials   to  be  used  when      Copyright ©2013 Enterprise jBilling Software Ltd

 

     16 

     

making non­authenticated API calls.  This   business   interface  is   specified  as   a  property   of  api:org.springframework.remoting.httpinvoker.HttpInvokerProxyFactoryBean.  This   pre­configured in jBilling to use IWebServicesSessionBean 

the  is  

Properties  ● serviceUrl  ­  The  service  URL  RMI  should  connect  to  (as  defined in the Connecting to  jBilling section of the Preparing jBilling for Integration  chapter of this document)  For example:    ● serviceInterface ­ This is the business interface that exposes the business functionality   

Integration with non­Java Applications  If  your  current  application  program  is   not  based  on  the  Java  platform/language,  you  can  still  integrate  your  system  with  jBilling  via  direct  SOAP  calls.  The  beauty   of  SOAP  is   that  it  is   independent  of any  particular language or framework  in order to be usable. SOAP is  available for  many,  if  not  all,  of the programming languages  commonly  used for Web. In this  document, we've  limited  ourselves   to  provide  two  of  the  most  used programming languages  for Web applications,  besides   Java  i.e. C#.NET and PHP. Both provide SOAP support. If your system of choice is  not  one  of  these,  please  refer  to  your  language's   documentation  for  clues   on  how  to  use  SOAP  service  calls  effectively. You can however use these examples  as  a guideline on how to perform  specific operations with jBilling.  The  provided  examples   perform  the  same  login  sequence  as   seen  in  an  earlier  section  of  this   document,  but  implementing  it  in  each  of  the  languages   and platforms. Once the implementation  in  your  specific   language  is   clear,  we  advise  you  to  follow  the  Integration  Tutorial  as   well,  since it provides  useful insight into the purpose of some of the most used web service calls. This   information  should  be  of  interest  even  if  your  system  is   not  built  on  Java,  as   it  explains   the  purpose of the calls, rather than their specific Java implementation. 

Integration with C# .NET  C#  .NET  provides   seamless   SOAP  support,  which  requires   no  extra  resources   to  be  added  to  your  application's   execution  environment.  Please  refer  to  the  MSDN  resources   for  latest      Copyright ©2013 Enterprise jBilling Software Ltd

 

     17 

     

information on what support options you have.  The  difficult  part  in  implementing  SOAP  on  C#  is   to  map  the  input  and  output  parameters   of the  web  call  into  appropriate  data  structures.  Since  there  are  many   different  calls,  it  quickly   gets   difficult to create all the necessary classes.  Therefore,  a  handy   utility,  distributed  as   part  of  the  Visual  Studio®;  distribution,  is   the  wsdl.exe.  This   utility   takes  care of converting a WSDL file into appropriate data structures  and  creates   an  output  file  that  contains   a  class   that  performs   all web service calls. You can find this   command line tool in the Visual Studio 8SDKv2.0Bin directory  of your Visual Studio installation.  Consult  your  Visual  Studio  documentation  or  just  call  wsdl.exe  with  no  parameters   to  obtain  some information on how to invoke this tool and what parameters are acceptable. 

If  you  use  SoapUI, an Open Source tool for testing and handling web services, you can also set  this   program  to  generate  the  necessary   .NET  files   (it  supports   generation  of  Managed  C++,  VisualBasic   and  J#  code,  as   well  as   C#).  Simply   indicate  the  location  of  the  above  mentioned  wsdl.exe tool in your system in the Preferences  dialog, connect to the jBilling web service url (as   defined  earlier)  from  SoapUI,  and  click   on  Tools  ­>  .NET  2.0  Artifacts  in the main menu. You'll  be  presented  with  a  set  of  generation  options   (WSDL  file  to  use  as   input,  output  directory,  the  user name and password to pass to the service, etc.). 

Once  the  class   containing  all  the  web  service  definitions   has   been  generated  (which  will  be  named  WebServicesSessionLocalService.cs),  it  is   a  simple  matter  of  using  the  generated class in your code, in a way that is akin to the jBilling Client API for Java:  using WebServicesSessionLocalService;  // create the interface instance of the class.  WebServicesSessionLocalService  service  WebServicesSessionLocalService();  int userId = service.getUserId(username);  if (userId > 0) {  UserWS userData = service.getUserWS(userId);  } 

= 

new 

Integration with PHP  PHP  provides   SOAP  support  via  an  add  on  library   (distributed  with  PHP  itself).  You'll  need  to  activate  the  library   support  in  your  PHP.INI  file  and  probably   need  a  library   file  (libxml)  to  be  present  in  your  system in order to use the SOAP support (refer to the PHP manual for details  on  how to activate SOAP support).  In  order  to  automate  the  generation  of  input  and  output  parameters   for  your SOAP request, you  may   use  the  PEAR  library,  which  comes   with  the  default  PHP  installation  (unless   you've  used      Copyright ©2013 Enterprise jBilling Software Ltd

 

     18 

     

the ­­without­pear configuration option during installation).  PEAR  can  generate  the  PHP  code  for  the  data classes  or it can generate the classes  on the fly   for  immediate  usage  on  the  program.  While  the  first  option  is   the  recommended  procedure  (this   way   you  can  avoid  parsing  and  generating  the  WSDL  file  each  time  your  code  executes),  for  simplicity   we'll  demonstrate  the  use  of  the  PEAR  module  with  the  second  option,  using  the  classes on the fly:  require_once 'SOAP/Client.php';  $requestParams = array ('user'=>'admin', 'pass'=>'asdfasdf');  $wsdl  =  SOAP_WSDL('http://localhost:8080/jbilling/services/api?wsdl',  $requestParams);  $client = $wsdl­>getProxy();  $userIdParams = array('in0' => $username);  $result = $client­>getUserId($userIdParams);  $userId = $result­>getUserIdReturn;  $userDataParams = array('in0' => $userId);  $result = $client­>getUserWS($userId);  $userData = $result­>getUserWSReturn; 

new 

This   is   quite  straightforward,  as   the  PEAR  library   has  done most of the dirty  work  of parsing the  WSDL  and  setting  up  the  calls.  The  $requestParamsis     an  associative  array   containing  the  user  name  and  password for the jBilling authentication. Parameters  for the web service calls  are  passed in associative arrays as well.  If  you  wish  to  generate  the  code  for  the  web  service  calls   for use in the program without having  to  parse  the  WSDL  every   time,  you  can  explore  how  to  generate  the  code  and  save  it  to  a  file  with the $wsdl­>generateProxyCode() function call of the SOAP_WSDL object.    A simple PHP example to create customer in jBilling :         

An Integration Tutorial  Overview This   section provides  an introduction to the use of jBilling integration calls. It builds  on the 'Trend'  tutorial  found  in  jBilling's   Getting  Started  guide.  As   such,  if  you  wish  to  follow  the  examples   in  this   section,  you'll  need  to  follow  the  Getting  Started  Guide  tutorial,  creating  the  Trend  entity   and  adding  the  Items   and Orders. The examples  in this  section will mainly  use the +jBilling client  API+.  If  you're  unable  to  use  this   API  (most  probably   because  your system does  not make use  of  the  Java  programming  language),  you'll  need  to  substitute  the  API  calls   with  direct  SOAP  requests.  Please,  refer  to  the  Integrating  jBilling  to  your  Application  chapter,  which  explains   the  options   for  performing  service  calls   to  jBilling  in  more  detail  and  provides   examples   for  some  programming languages and SOAP APIs available. 

The Trend Website  In  the  Getting  Started  guide,  you  were  introduced  to  jBilling's   capabilities   by   means   of  a  small  tutorial  centered  around  a  hypothetical  'Trend'  company,  which  runs   a  website.  Following  the  tutorial,  you  were  able  to  create  the  Trend  entity,  added  an  Item  and  created  an  Order  and  an  Invoice.  We'll  build  on  this   example,  examining  how  jBilling's   integration  features   could  be  applied to the Trend website, which needs to integrate with jBilling. 

Controlling access to the 'Paid' Area of the website  Being  a  paid  service,  the  Trend  website  obviously   needs   to  determine  whether  each  user  that  enters   the  site  is   a  paying  customer  or  not,  in  order  to  provide  its   services   only   to  those  that  have  paid  for  it.  This   can  be  accomplished  by   the  use  of  the  usual  user  name/password  pair,  which  will  be  provided  to  each  customer  at  the  end  of  the  subscription  process,  once  the  first  payment has cleared. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     22 

     

Of  course,  the  invoicing  and  payment are handled by  jBilling, therefore the website needs  a way   of knowing when the given user­name has become a paying customer.  A  solution could be to maintain a local record of customers  and check  each login attempt against  it,  but  this   actually   represents   a  problem:  how  would  the  program  know  when  a  customer  has   paid  or  not?  Without  any   integration  calls,  someone  would  have  to  keep  the  data  in  this   record  updated, a manual operation that could introduce errors and takes time.  Another  important  consideration  is   that  the  website  charges   its   customers   a  monthly   fee.  This   means   the  status   of  customers   could  change  at  any   time,  if  the  user,  for  example, has  not paid  the  fee  for  the  current  month  (it  would  fall  back   to  non­paying).  A  local  record  of  customers   would not have this information, at least not until the next manual update.  The  solution  is   throwing  in  an  integration  call  to  jBilling  to  ensure  the customer at hand has  paid  his   fee  and  is   authorized  to  access   the  website's   resources.  jBilling  takes   care  of  checking  its   internal  data  and  determines   if  the  client's   payment  has   been  processed  and  whether  his   subscription is still valid.  The  website's   login  form  retrieves   the  customer's   username  and  password,  performs   any   local  validations  and checks  the user's  status  in jBilling (which will indicate his  current payment status   and therefore whether he should be authorized to login or not).  The  first  step  (regarding  integration  calls   and  not  local  validation)  is   therefore  to  retrieve  the  jBilling's   +User  ID+  number,  and  request  the  user's   data,  so  that  the  current  status   can  be  determined. The sequence would be:  import com.sapienter.jbilling.server.util.api.JbillingAPI;  import com.sapienter.jbilling.server.util.api.JbillingAPIFactory;  import com.sapienter.jbilling.server.user.UserWS;  /*  * We assume the String variable "username" contains the username  * string as entered by the user in the login form.  */  Integer userId = null;  // Create and initialize the *j*Billing API.  JbillingAPI api = JbillingAPIFactory.getAPI();  boolean canLogin = false;  try {  userId = api.getUserId(username);  if (userId == null) {  /*  *  This  shouldn't  happen  as  the  API  should  issue  an  exception if the  * user does not exist, but test it anyway. In this case,  we simply  * generate an exception that is catched later in this      Copyright ©2013 Enterprise jBilling Software Ltd

 

     23 

     

block  * of code.  */  }  // With the user id just retrieved, we can query the user's  data.  UserWS userData = api.getUserWS(userId);  /*  * The user data contains many information about the user, but in  * this case we're mostly interested in the statusId field of the  * UserWS class.  * This field values are: 1=active, 2=Overdue 1, 3=Overdue 2,  * 4=Overdue 3, 5=Suspended 1, 6=Suspended 2, 7=Suspended 3,  * 8=Deleted. Status Ids from 1 through 4 indicate the user is  able  * to login, all other codes cannot login.  */  int statusId = userData.getStatusId().intValue();  if (statusId > 0 && statusId  Periods". 

periodStr 

api:java.lang.String 

(read only). The description of the  order period. 

pricingFields 

api:java.lang.String 

An array of pricing fields encoded as  a String. To encode, use the  PricingField.setPricingFieldsValue()  static method, which takes as  parameter an array of PricingField  structures and returns the encoded  string. To decode, use the  PricingField.getPricingFieldsValue()  static method, which takes as  parameter an encoded string and  returns an array of PricingField  structures. Pricing fields are  descriptors that provide further  information to the pricing engine and  aid in forming the price for the order  itself. See section "A word on  pricing" for a more detailed  explanation of the use of pricing  fields. 

statusId 

api:java.lang.Integer 

An order has to be on status 'Active'  in order to generate invoices. An  order usually starts in active status,  and only goes to suspended or  finished when the customer fails to  make the required payments. The  steps and actions taken due to late  payments are part of the ageing  process. See Appendix A for a list of  acceptable order status codes. 

statusStr 

api:java.lang.String 

(Read only) The description of the  current order status. 

timeUnitStr 

api:java.lang.String 

(Read only) The description of the  time unit used for billable periods. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     47 

      total 

api:java.lang.String 

(Read only) A string representation  of the api:java.math.BigDecimal  value of sum­total of all the order  lines of this order, in other words,  total order amount. 

userId 

api:java.lang.Integer 

An identifier for the User to whome  thiis order belongs. 

metaFields 

MetaFieldValueWS 

User defined fields. 

versionNum 

Integer 

Keeps track of number of times this  object has been updated. 

Property 

Type 

Description 

amount 

String 

The total amount of this line. Usually,  this field should equal to the product  of price and quantity. This amount  will be the one added to calculate  the purchase order total. The  currency of this field is the one  specified in its parent order. The  amount can be also set and  obtained as a  api:java.math.BigDecimal, using the  getAmountAsDecimal() and  setAmountAsDecimal() methods. 

createDatetime 

api:java.util.Date 

A time stamp applied when this  record is created. 

deleted 

api:java.lang.Integer 

A flag that indicates if this record is  logically deleted in the database.  This allows for 'undo' of deletions.  Valid values are 0 � the record is  not deleted 1 � the record is  considered deleted. 

description 

api:java.lang.String 

A descriptive text for the services  being included. This usually copies  the description of the item related to  this line. 

editable 

api:java.lang.Boolean 

Indicates whether this order line is  editable or not (i.e., it cannot be  submitted for update). 

id 

api:java.lang.Integer 

A unique number that identifies this  record. 

itemDto 

ItemDTOEx 

Contains information of the item this  order line refers to. 

itemId 

api:java.lang.Integer 

The id of the item associated with  this line, or null if this line is not 

OrderLineWS 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     48 

      directly related to an item. It is  consider a good practice to have all  order lines related to an item. This  allows for better reporting.  orderId 

api:java.lang.Integer 

Identifier of the order that contains  this order line. 

price 

api:java.lang.String 

The price of one item, or null if there  is no related item. Can also be  manipulated as a  api:java.math.BigDecimal using the  "getPriceAsDecimal()" and  "setPriceAsDecimal()" methods. 

priceStr 

api:java.lang.String 

The price of the item as a string. 

provisioningRequestId 

api:java.lang.String 

The provisioning request UUID for  this order line, if it exists. 

provisioningStatusId 

api:java.lang.Integer 

The provisioning status id for this  order line. See Appendix A for valid  values. 

quantity 

api:java.lang.String 

The quantity of the items included in  the line, or null, if a quantity doesn't  apply. It can also be handled using  the "getQuantityAsDecimal()" and  "setQuantityAsDecimal()" methods. 

typeId 

api:java.lang.Integer 

An order line usually has items.  However, some lines are used for  additional charges, like taxes. See  Appendix A for a list of acceptable  order line type codes. 

useItem 

api:java.lang.Boolean 

If true, when submitted, this line will  take the price and description from  the item. This means that you would  not need to give a price and  description for the line. Instead, you  only provide the id of the item. See  the createOrder section for details. 

orderLinePlanItems 

OrderLinePlanItemWS 

Can overwrite the quantity & price of  the plan items at order creation  level. 

versionNum 

Integer 

Keeps track of number of times this  object has been updated 

Property 

Type 

Description 

invoiceId 

Integer 

Identifier of the invoice that was  generated. 

CreateResponseWS 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     49 

      orderId 

api:java.lang.Integer 

Identifier of the order that was  created. 

paymentId 

api:java.lang.Integer 

Identifier of the payment that was  generated to pay the invoice. 

paymentResult 

PaymentAuthorizationDTOEx 

Payment Result data structure with  the outcome details of the payment  operation. 

userId 

api:java.lang.Integer 

Identifier of the new user created  and for which the order, invoice and  payment were created. 

PricingField  This   data structure describes  heterogeneous  data that will be passed to the rules  engine in order  to calculate prices and/or flag specific conditions that affect pricing:  Property 

Type 

Description 

name 

api:java.lang.String 

Identifier of the pricing field. 

position 

api:java.lang.Integer 

(optional) 

value 

api:java.lang.String 

A multipurpose String value of the  pricing field, which can be used as  deemed fit within the rules (for  example, use the string value as a  description for the Item). 

type 

enum: Type 

Enumeration for data type(String,  Integer, Decimal, Date, Boolean ) . 

resultId 

Long 

Identifier of the Mediation result gets  stored. Only used for mediation of  batch. 

Item Management Calls  Items   are  the  building  blocks   of  purchase  orders. Items  are usually  managed from the GUI Web  App  since  they   don't  have  the  level  of  activity   of  orders   or  payments.  Use  this   service  for  integration  with  other  applications   (for  example,  an  inventory   system)  or  when  handling  high  volumes   to  get  better  throughput  as   compared  to  the  Web  Application.  An  item  can  have  a  simple  price  or  a percentage price. Items  with a simple price will simply  add that price to the total  of  a  purchase  order.  A  percentage  price  will  impact  that  total  by   a  percentage.  Examples   of  items with percentage prices are taxes and interests. 

ItemDTOEx  Property 

Type 

Description 

currencyId 

api:java.lang.Integer 

Identifier for the currency in which 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     50 

      the item's price is expressed. See  Appendix A for a list of acceptable  values.  deleted 

api:java.lang.Integer 

A flag that indicates if this record is  logically deleted in the database.  This allows for 'undo' of deletions.  Valid values are: 0 � the record is  not deleted 1 � the record is  considered deleted. 

entityId 

api:java.lang.Integer 

Identifier for the entity to which this  item belongs. 

hasDecimals 

api:java.lang.Integer 

An internal flag indicating whether  the item accepts decimal quantities.  Can have the following values: 0 �  No decimals, quantities are  expressed as an integer, 1 �  Decimals allowed in quantity values. 

id 

api:java.lang.Integer 

A unique number that identifies this  Item record. 

orderLineTypeId 

api:java.lang.Integer 

The order line type that this item will  generate, such a 'taxes', or 'items'. 

types 

Integer 

A list of type identifiers that indicates  to which types (categories) this item  belongs. An item must belong to at  least one type. 

defaultPrice 

PriceModelWS 

A default pricing model this Item  follows. See PriceModelWS 

description 

api:java.lang.String 

Item description 

glCode 

api:java.lang.String 

General Ledger code for integration  with Other systems like Accounting  Systems. 

number 

api:java.lang.String 

This can be used to identify this item  following an external coding system.  For example, books can be  identified by their ISBN codes. 

percentage 

api:java.math.BigDecimal 

If this Item has percentage rate, that  rate is specified using this field 

price 

api:java.math.BigDecimal 

The price of this item or null if this is  a percentage item. 

promoCode 

api:java.lang.String 

If this item is related to a promotion,  this is the code that identifies the  promotion. 

metaFields 

MetaFieldValueWS 

List of user defined fields. 

excludedTypes 

Integer 

Array of product that does not 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     51 

      belong to other categories.  descriptions 

InternationalDescriptionWS 

List of descriptions of the product in  the other languages. 

defaultPrices 

Map 

Default Price of the product for that  date & with specified pricing  strategy.  

Property 

Type 

Description 

id 

api:java.lang.Integer 

A unique number that identifies this  record 

type 

api:java.lang.String 

String value representing the  PricingStrategy type name 

attributes 

SortedMap 

A map of Price model attributes.  Different attributes (name, value  pairs) are required by individual  PricingStrategy types for use in the  calculation of price 

rate 

api:java.lang.String 

A decimal value of the available rate  in string. This is a default rate that is  used for Price calculate, unless  overridden by a PricingStrategy rate 

currencyId 

api:java.lang.Integer 

The currency used for this  PriceModel 

next 

PriceModeWS 

The next PriceModel for the plan that  references this PriceModel 

Property 

Type 

Description 

description 

String 

Description for this item type. 

id 

api:java.lang.Integer 

Identifier of this item type. 

orderLineTypeId 

api:java.lang.Integer 

Type of order line for this item. See  "Order Line Type Codes" in  "Appendix A" for valid values for this  field. 

PriceModelWS 

  ItemTypeWS 

ValidatePurchaseWS  Property 

Type 

Description 

authorized 

Boolean 

true if the validation has 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     52 

     

been authorized, false  otherwise.  message 

String 

An array of messages  detailing the result of the  validation operation. 

quantity 

api:java.lang.String 

Quantity of the item that can  be applied without exceeding  the user's remaining credit  limit or prepaid balance. 

success 

api:java.lang.Boolean 

true if the validation was  successful, false otherwise. 

 

Invoice Management Calls  The  invoice  management  calls   allow  your application to query  the system about invoices, and to  attempt  to  pay   an  invoice  through  a  payment  gateway.  Invoices   in  jBilling  are, for the most part,  read­only   and  are  created  based  on  purchase  orders.  Invoices   can  be  generated,  however,  for  orders that have yet to be invoiced. 

InvoiceWS  Property 

Type 

Description 

createDateTime 

api:java.util.Date 

This is the invoice date, which is  assigned to it by the billing process  when it is generated. 

createTimeStamp 

api:java.util.Date 

A time stamp of when this invoice  record was created. 

dueDate 

api:java.util.Date 

The due date of this invoice. After  this date, the invoice should have  been paid. 

lastReminder 

api:java.util.Date 

Date and time of when the latest  reminder was issued for this invoice. 

currencyId 

api:java.lang.Integer 

Identifier of the currency in which the  invoice's amounts are being  expressed. See Appendix A for a list  of all acceptable values. 

delegatedInvoiceId 

api:java.lang.Integer 

If this invoice has been included in  another invoice (usually for lack of  payment), this field will indicate to  which invoice it has been delegated. 

deleted 

api:java.lang.Integer 

A flag that indicates if this record is 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     53 

      logically deleted in the database.  This allows for 'undo' of deletions.  Valid values are: 0 � the record is  not deleted 1 � the record is  considered deleted.  id 

api:java.lang.Integer 

A unique number that identifies this  record. 

inProcessPayment 

api:java.lang.Integer 

A flag indicating if this invoice will be  paid using automated payment  (through a payment processor), or if  it will be paid externally (for  example, with a paper check). 

isReview 

api:java.lang.Integer 

This is an internal value that  indicates if this invoice is not a 'real'  invoice, but one that belongs to a  review process. If '1', it means that it  is not a real Invoice. 

orders 

Integer 

A list of the ids of the purchase  orders which have been included in  this invoice. 

overdueStep 

api:java.lang.Integer 

This marks which step is this invoice  in for the penalties (interests)  process. 

paymentAttempts 

api:java.lang.Integer 

How many payment attempts have  been done by the automated  payment process to get this invoice  paid. 

payments 

Integer 

A list of ids of the payments that  have been applied to this invoice. 

statusId 

api:java.lang.Integer 

A flag that indicates the status of this  invoice. See section Invoice Status  Codes on Annexure A for valid  values for this field. 

toProcess 

api:java.lang.Integer 

This is '1' if the invoice will be  considered by the billing process as  unpaid. Otherwise it is '0' and the  invoices is either paid or carried  over to another invoice. 

userId 

api:java.lang.Integer 

The customer to whom this invoice  belongs. 

invoiceLines 

InvoiceLineDTO 

A list of objects representing each of  this invoice's lines. 

balance 

api:java.lang.String 

The amount of this invoice that is yet  to be paid. Can also be handled as  a api:java.math.BigDecimal via the  "getBalanceAsDecimal()" and 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     54 

      "setBalanceAsDecimal()" methods.  carriedBalance 

api:java.lang.String 

How much of the total belonging to  previous unpaid invoices that have  been delegated to this one. It can  also be handled via the  "getCarriedBalanceAsDecimal()"  and  "setCarriedBalanceAsDecimal()"  methods. 

customerNotes 

api:java.lang.String 

Notes that are entered in a purchase  order can be applied to an invoice. If  that is the case, this field will have  those user notes. 

number 

api:java.lang.String 

The invoice number, which is  assigned to it from a 'preference'  field (see the user guide for more  information). This is not the ID, which  is guaranteed to be unique. 

statusDescr 

api:java.lang.String 

The status name of the Invoice  status as determined from the field  statusId 

total 

api:java.lang.String 

The total amount of this invoice. It  can also be handled as a  api:java.math.BigDecimal via the  "getTotalAsDecimal()" and  "setTotalAsDecimal()" methods. 

metaFields 

MetaFieldValueWS 

A list of user defined fields. 

billingProcess 

BillingProcessWS 

Retruns billing processws for which  invoices has generated. 

InvoiceLineDTO  This data structure contains data relative to a single line of an invoice.  Property 

Type 

Description 

amount 

api:java.math.BigDecimal 

The total amount for this line.  Usually would follow the formula  price * quantity. 

deleted 

api:java.lang.Integer 

A flag that indicates if this record is  logically deleted in the database.  This allows for 'undo' of deletions.  Valid values are: 0 � the record is  not deleted 1 � the record is  considered deleted. 

description 

api:java.lang.String 

This description will be displayed in  the invoice delivered to the 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     55 

      customer.  id 

api:java.lang.Integer 

A unique number that identifies this  record. 

isPercentage 

api:java.lang.Integer 

Indicates whether the item  referenced by this invoice line is a  percentage item or not. This is used  to aid how the order line is displayed  to the customer. 

itemId 

api:java.lang.Integer 

Identifier of the item referenced by  this invoice line. 

price 

api:java.math.BigDecimal 

The pricing of a single unit of this  item. 

quantity 

api:java.math.BigDecimal 

The number of units of the item  being invoiced. 

sourceUserId 

api:java.lang.Integer 

This field is useful only when many  sub­accounts is invoiced together.  This field would have the ID of the  user that originally purchase an  item. 

  Payment Management Calls  Payments   play   a  crucial  role  in  determining the status  of a customer. For the system to properly   trace  payments,  they   have  to  be  linked  to  the  invoices  they  are paying. Payments  not related to  an  invoice  should  be  avoided;  they   are  intended  for  initial  imports   from  legacy   billing  systems   and  exceptional  circumstances.  Arbitrary   credit  card  payment  processing  not  linked  to  any   invoice  is   possible,  however.  There  are  three  basic   payment  methods:  Cheques,  ACH  and  Credit  Cards.  Different objects  are used as  fields  of PaymentWS for each for these types. There  are  two  different  actions   related  to  payments.  One  is   to  apply   a  payment.  This   means   that  the  payment  has   already   been  processed  and  accepted  by  the company. Applying the payment will  let  the  system  know  that  a  new  payment  has   to  be  registered.  A  common  example  is  when the  company   has   received  and  successfully   deposited  a  cheque.  In  this  case, the system only  has   to  apply   the  payment  to  the  customer's   account.  A  more  comprehensive  action  is   to  process   a  payment.  Processing  a  payment  means   the  company   will  submit the payment information to the  system,  then  the  system  will  submit  the  payment  to  a  payment  process   for  its   authorization  in  real­time,  storing  the  result  of  this   operation.  The  caller  will  get  the  results   of  this   authorization.  The  most  common  example  for  this   operation  is  a credit card payment. In summary, the system  can  both  request  authorization  of  a  payment  and  apply   the  payment  to  the  customer's  account,  or  it  can  do  only   this   last  step.  The  payment  management  calls  will let you query  the system for  payments, and also apply and submit a payment to get an invoice payed. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     56 

     

PaymentWS  Property 

Type 

Description 

ach 

AchDTO 

If this is a payment done with  Automatic Clearing House (ACH),  this property contains the banking  information needed. 

amount 

api:java.lang.String 

The amount of the payment  operation. Can also be handled as a  api:java.math.BigDecimal via the  "getAmountAsDecimal()" and  "setAmountAsDecimal()" methods. 

authorization 

PaymentAuthorizationDTO 

Refund specific field. Contains the  identifier of the authorization details  for the refund. 

balance 

api:java.lang.String 

Balance of this payment. If greater  than 0, this payment could pay part  of another invoice. If 0, this payment  has already been applied to an  invoice, lowering the invoice's  balance. It can also be handled as a  api:java.math.BigDecimal via the  "getBalanceAsDecimal()" and  "setBalanceAsDecimal()" methods. 

cheque 

PaymentInfoChequeDTO 

If this payment is done via check,  this property contains information  about the cheque, otherwise it  contains "null". 

createDatetime 

api:java.util.Date 

Date in which this payment record  was created. 

creditCard 

CreditCardDTO 

If this is a credit card payment, this  property contains information about  the credit card, otherwise it contains  "null". 

currencyId 

api:java.lang.Integer 

Identifier of the currency in which the  payment is being made. See  Appendix A for a list of acceptable  values. 

deleted 

api:java.lang.Integer 

Delete flag. '1' if this record has been  deleted, '0' otherwise. 

attempt 

api:java.lang.Integer 

Number of the attempt to process  this payment. 

id 

api:java.lang.Integer 

Unique identifier of the payment  record. 

invoiceIds 

Integer 

Contains the list of invoices this 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     57 

      payment is paying.  isPreauth 

api:java.lang.Integer 

'1' if this payment is a  preauthorization, '0' otherwise. 

isRefund 

api:java.lang.Integer 

'1' if this payment constitutes a  refund operation, '0' otherwise. 

method 

api:java.lang.String 

Name of the payment method used. 

paymentDate 

api:java.util.Date 

Date of the payment. 

paymentId 

api:java.lang.Integer 

Refund specific field. When a refund  is to be issued, this field holds the  identifier of the payment that is to be  refunded. 

paymentMethodId 

api:java.lang.Integer 

Identifier of the payment method.  Refer to Appendix A for a list of  acceptable values. 

paymentNotes 

api:java.lang.String 

Any notes related to this payment for  e.g. relevant invoiceId can be added  to notes or any relevant information. 

paymentPeriod 

api:java.lang.Integer 

Optional Payment period identifier 

resultId 

api:java.lang.Integer 

Identifier of the result of the payment  attempt. Refer to Appendix A for a  list of acceptable values. 

updateDatetime 

api:java.util.Date 

Date in which this payment record  was last updated. 

userId 

api:java.lang.Integer 

Identifier of the user this payment  record belongs to. 

metaFields 

MetaFieldValueWS 

A list of user defined fields. 

PaymentInfoChequeDTO  Property 

Type 

Description 

id 

api:java.lang.Integer 

The unique identifier of this record. 

bank 

api:java.lang.String 

The name of the bank this cheque's  account belongs to. 

number 

api:java.lang.String 

The cheque's number. 

date 

api:java.util.Date 

The cheque's date. 

idHasBeenSet 

Boolean 

A Value Object has an identity if the  attributes making its Primary Key  have all been set. An object without  identity is never equal to any other  object. Returns true if this instance  has an identity. 

bankHasBeenSet 

Boolean 

True if bank is set otherwise false.  

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     58 

      numberHasBeenSet 

Boolean 

True if number is set otherwise false. 

dateHasBeenSet 

Boolean 

True if date is set otherwise false. 

pk 

Integer 

Returns primary key. 

Property 

Type 

Description 

abaRouting 

api:java.lang.String 

ABA routing number. 

accountName 

api:java.lang.String 

The account name. 

accountType 

api:java.lang.Integer 

If this is chequings or a savings  account. 

bankAccount 

api:java.lang.String 

The account number. 

bankName 

api:java.lang.String 

The bank name. 

id 

api:java.lang.Integer 

The unique identifier of this record. 

idHasBeenSet 

Boolean 

True if id is set otherwise false. 

abaRoutingHasBeenSet 

Boolean 

True if ABA routing number is set  otherwise false. 

bankAccountHasBeenSet 

Boolean 

True if bank account is set otherwise  false. 

accountTypeHasBeenSet 

Boolean 

True if account type is set otherwise  false. 

bankNameHasBeenSet 

Boolean 

True if bank name is set otherwise  false. 

accountNameHasBeenSet 

Boolean 

True if account name is set  otherwise false. 

gatewayKey 

String 

The payment gateway key. 

gatewayKeyHasBeenSet 

Boolean 

True if gateway key is set otherwise  false. 

pk 

Integer 

Id value is set in it.  

AchDTO 

PaymentAuthorizationDTO  Property 

Type 

Description 

id 

api:java.lang.Integer 

Unique identifier of the payment  authorization. 

processor 

api:java.lang.String 

Name of the payment processor. 

code1 

api:java.lang.String 

Request code number 1. 

code2 

api:java.lang.String 

Request code number 2. 

code3 

api:java.lang.String 

Request code number 3. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     59 

      approvalCode 

api:java.lang.String 

Approval code provided by the  processor. 

AVS 

api:java.lang.String 

A code with the results of address  verification. 

transactionId 

api:java.lang.String 

Identifier of the processor  transaction. 

MD5 

api:java.lang.String 

Hash for the transaction. 

cardCode 

String 

Payment card code. 

createDate 

Date 

The creation date for this payment  authorization record. 

responseMessage 

String 

The response provided by the  processor. 

idHasBeenSet 

Boolean 

True if id is set otherwise false. 

paymentId 

Integer 

Identifier of the payment. 

processorHasBeenSet 

Boolean 

True if processor is set otherwise  false. 

code1HasBeenSet 

Boolean 

True if code1 is set otherwise false. 

code2HasBeenSet 

Boolean 

True if code2 is set otherwise false. 

code3HasBeenSet 

Boolean 

True if code3 is set otherwise false. 

approvalCodeHasBeenSet 

Boolean 

True if approval code is set  otherwise false. 

AVSHasBeenSet 

Boolean 

True if AVS is set otherwise false. 

transactionIdHasBeenSet 

Boolean 

True if transactionId is set otherwise  false. 

MD5HasBeenSet 

Boolean 

True if MD5 is set otherwise false. 

cardCodeHasBeenSet 

Boolean 

True if card code is set otherwise  false. 

createDateHasBeenSet 

Boolean 

True if card date is set otherwise  false. 

responseMessageHasBeenSet 

Boolean 

True if response message is set  otherwise false. 

pk 

Integer 

 

PaymentAuthorizationDTOEx  This   data  structure  contains   data  about  a  payment  authorization  process.  It  extends   the  PaymentAuthorizationDTO  structure  (see  above).  Thus,  it  shares   all  the  same  fields   plus   the  following:  Property 

Type 

Description 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     60 

      result 

api:java.lang.Boolean 

true if the authorization succeeded,  false otherwise. 

API Service Calls  The  Service  APIs/Calls   are  grouped  according  to  functional  area  or  data  entities   in  jBilling,  for  example:  User  Management  APIs,  Orders,  Items,  etc.  All  data  contained  in  the  Client  API  data  structures   can  be  accessed  by   means   of  the  getter  and  setter  methods   of  each  property   (i.e.,  getFaxNumber()and     setFaxNumber()provide     access   to  the  faxNumber  property).  When  describing  data  structures,  this   guide  always   provides   the  property   name.  This   reference  is   equally   useful  for  those  planning  to  use  the  web  services   directly,  or  for  those that will be using  the  jBilling  Client  API.  For  non­Java  languages,  the  data  structures   will  look   slightly   different:  they   are  described  in  the  WSDL  descriptor  and  how  that  is   translated  to  each  language  varies.  For  those  using  the  jBilling  Client  API  from  a  Java  application,  the  data  structures   can  be  used  directly as classes.  For  a  finer  coverage  of  the  SOAP  support,  refer  to  the  WSDL  file  or  use  a  SOAP  introspection  tool  (such  as   SoapUI).  All  the SOAP methods, however, share the same name, parameters  and  functionality as their API counterparts.  All service calls provided by the API are covered in the Web Services API Reference docs.  Please refer to the client/Web Services API from here: API Reference. 

 

Web­Services API Reference  Invoice API Methods  API Method 

Arguments 

Returns 

Description 

getInvoiceWS(Integer  invoiceId) 

Invoice ID 

InvoiceWS 

Returns  the  invoice  for  the  given  ID.  Will  return null if invoice is a review invoice. 

createInvoice(Integer  userId,  User  ID,  Orders  to  Integer  boolean onlyRecurring)  include 

Creates  an  invoice  for  the  given  user,  including all orders or only recurring orders.  Returns  the  an  array  of  generated  invoice  IDs. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     61 

      createInvoiceFromOrder(Inte Order  ID,  Invoice  Integer  ger orderId, Integer invoiceId)  ID 

Creates  an  invoice  for  the given order. If an  invoice  ID  is  given,  the  order  will  be added  to  the  selected  invoice  ­  Otherwise  a  new  invoice will be created. 

deleteInvoice(Integer  invoiceId) 

­ 

Deletes the given invoice. 

getAllInvoicesForUser(Intege User ID  r userId) 

InvoiceWS 

Returns  an  array  of  invoices  for  the  given  user. 

getAllInvoices(Integer userId)  User ID 

Integer 

Returns an array of invoice IDs for the given  user. 

getLatestInvoice(Integer  userId) 

User ID 

InvoiceWS 

Returns  the  most  recent  invoice  for  the  given user. 

getLastInvoices(Integer  userId, Integer number) 

User ID, number of  Integer  invoices 

Returns  the  last  N  invoice  IDs  for  the given  user. 

getInvoicesByDate(String  since, String until) 

Date  range  in  the  Integer  format  "yyyy­mm­dd" 

Returns  an  array  of  invoice  IDs  created  between the given dates. 

getUserInvoicesByDate(Integ User  ID,  Date  Integer  er  userId,  String  since,  String  range in the format  until)  "yyyy­mm­dd" 

Returns  an  array  of  invoice  IDs  created  between the given dates for the given user. 

getUserInvoicesPage(Integer  UserID,  userId,  Integer  limit,  Integer  Offset   offset) 

Returns  an  array  of invoicews  between the  given range  for the given user. 

getUnpaidInvoices(Integer  userId) 

Invoice ID 

User ID 

Limit,  InvoiceWS 

Integer 

Returns  an  array  of  un­paid  invoice  IDs  for  the given user. 

notifyInvoiceByEmail(Integer  Invoice ID  invoiceId) 

Boolean  success 

Sends  a  notification  to  the  user  regarding  the given invoice ID. 

getPaperInvoicePDF(Integer  Invoice ID  invoiceId) 

Byte 

Returns  the  generated  PDF  invoice  as  a  Base64­encoded string. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     62 

      notifyPaymentByEmail(Intege Payment ID  r paymentId) 

createInvoiceWithDate(Integ er  userId,  Date  billingDate,  Integer  dueDatePeriodId,  Integer  dueDatePeriodValue,  boolean onlyRecurring) 

Boolean 

User  ID,  Billing  Integer  Date,  Due  Date  Period  ID,  Due  Date  Period  Value,  Boolean  Only Recurring 

applyOrderToInvoice(Integer  Order  orderId,  InvoiceWS  InvoiceWS  invoiceWs) 

ID,  Integer 

Sends an email with the Payment  information to the customer. 

        Generates an invoice for a customer using  an explicit billing date & due date period. If  the billing date is left blank, the invoice will  be generated for today.  If the due date period unit or value is left  blank, then the due date will be calculated  from the  order period, or from the customer due date  period if set.  Returns an array of generated invoice ids.          Generate an invoice using given order ID.  Creates an invoice template that contains  the meta field values using InvoiceWS &  returns invoice Id. 

 

Order API Methods  API Method 

Arguments 

Returns 

Description 

getOrder(Integer orderId) 

Order ID 

OrderWS 

Returns the order for the given ID. 

createOrder(OrderWS order) 

OrderWS 

Integer 

Saves the given order and returns the new  ID. 

updateOrder(OrderWS order)  OrderWS 

­ 

Updates the stored order details to match  the given order. Given order must have an  ID. 

createUpdateOrder(OrderWS  OrderWS  order) 

Integer 

Saves the order if it does not already exist,  or updates the stored details if it does. 

deleteOrder(Integer id) 

Order ID 

­ 

Deletes the given order. 

createOrderAndInvoice(Order WS order) 

OrderWS 

Integer 

Saves the given order and immediately  generates an invoice for the new order.  Returns the ID of the new invoice. 

getCurrentOrder(Integer  userId, Date date) 

User ID, Date 

OrderWS 

Returns the current order (order collecting  current one­time charges) for the period of  given date. 

OrderWS 

Returns an array of recurring order lines  for the given user. 

getUserSubscriptions(Integer  User ID  userId)      Copyright ©2013 Enterprise jBilling Software Ltd

 

     63 

      getOrderLine(Integer  orderLineId) 

Order Line ID 

updateOrderLine(OrderLineW OrderLineWS  S line)  getOrderByPeriod(Integer  userId, Integer periodId) 

OrderLineWS 

Returns the order line for the given ID. 

­ 

Updates the stored order line details to  match the given order line. Given order  line must have an ID. 

User ID, Period ID  Integer 

Returns an array of order IDs for the given  user and period id (One­time period,  Monthly period etc.). 

getLatestOrder(Integer userId)  User ID 

OrderWS 

Returns the most recent order for the given  user. 

getLastOrders(Integer userId,  User ID, Integer  Integer number)  number 

Integer 

Returns the last N order IDs for the given  user. 

rateOrder(OrderWS order) 

OrderWS 

OrderWS 

Processes the given order, calculating  prices and running all item management  plug­ins. Returns the order as it would  have been created. 

rateOrders(OrderWS orders) 

OrderWS 

OrderWS 

Rates a list of orders and returns the result. 

updateOrderPeriods(OrderPer Order Periods  iodWS orderPeriods) 

boolean  success 

Updates all order periods to match the  given list of periods. 

deleteOrderPeriod(Integer  periodId) 

Order Period ID 

boolean  success 

Deletes the given order period. 

createOrderPreAuthorize(Ord erWS order) 

OrderWS 

PaymentAuthori Creates the given order, and attempts to  zationDTOEx  pre­authorize a payment for the total order  amount. 

updateCurrentOrder(Integer  userId, OrderLineWS[] lines,  PricingField[] fields, Date date,  String eventDescription)   

User Id,  OrderWS  OrderLineWS,    PricingField, Date,  Event Description   

Updates the uesr's current one­time order  for the given date. Returns the updated  current order. Throws an exception for  users with no main subscription order. 

updateOrCreateOrderPeriod( OrderPeriodWS orderPeriod)   

OrderPeriodWS 

Boolean   

Update order period if already exists  orthewise create new order period & save  it. 

getOrderPeriods() 

­ 

OrderPeriodWS  Returns an array of orderPeriodWS.  

 

   

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     64 

     

Item API Methods  API Method 

Arguments 

Returns 

Description 

getItem(Integer  itemId,  Integer  Item  ID,  User  ID,  ItemDTOEx  userId, String pricing)  Pricing string 

Returns the item for the given ID. 

getAllItems() 

­ 

ItemDTOEx 

Returns an array of all items in the system. 

createItem(ItemDTOEx item) 

ItemDTOEx 

Integer 

Save  the  given  item  and  returns  the  new  ID. 

updateItem(ItemDTOEx item) 

ItemDTOEx 

­ 

Updates  the  stored  item  details  to  match  the  given  item.  Given  item  must  have  an  ID. 

deleteItem(Integer itemId) 

Item ID 

­ 

Deletes the given item. 

getItemByCategory(Integer  itemTypeId) 

Item Type ID 

ItemDTOEx 

Returns  an  array  of  items belonging to the  given item type. 

getUserItemsByCategory(Inte User  ID,  Item  Type  Integer  ger userId, Integer categoryId)  ID 

Returns  all  items  for  the  given  category  that  can  be  found  on  an  active  order  for  the given user. 

getAllItemCategories() 

­ 

ItemTypeWS 

Returns  an  array  of  all  item  types  in  the  system. 

createItemCategory(ItemType WS itemType) 

ItemTypeWS 

Integer 

Saves  the  given  item  type  and  returns  the  newly created object. 

updateItemCategory(ItemType ItemTypeWS  WS itemType) 

­ 

Updates  the  stored  item  type  and  returns  the  updated  object.  Given  item  type  must  have an ID. 

deleteItemCategory(Integer  itemCategoryId) 

­ 

Deletes the given item type. 

Item Type ID 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     65 

      isUserSubscribedTo(Integer  userId, Integer itemId) 

User ID, Item ID 

String 

Returns  the  total  quantity  of  an  item found  on a users active recurring orders. 

getLatestInvoiceByItemType(I User  ID,  Item  Type  InvoiceWS  nteger  userId,  Integer  ID  itemTypeId) 

Returns  the  latest  invoice  for  a  user  containing an item of the given type. 

getLastInvoicesByItemType(In User  ID,  Item  Type  Integer  teger  userId,  Integer  ID, Integer number  itemTypeId, Integer number) 

Returns  the  last  N  invoice  IDs  containing  an item of the given type for a user. 

getLatestOrderByItemType(Int User  Id,  Item  Type  OrderWS  eger  userId,  Integer  ID  itemTypeId) 

Returns  the  latest  order  for  a  user  containing an item of the given type. 

getLastOrdersByItemType(Inte User  ID,  Item  Type  Integer  ger userId, Integer itemTypeId,  ID, Integer number  Integer number) 

Returns  the  last  N  order IDs containing an  item of the given type for a user. 

getUserOrdersPage(Integer  User, Limit, Offset    OrderWS  user,  Integer  limit,  Integer  offset) 

Returns  an  array  of  orderws  between  the  given range for the given user. 

validatePurchase(Integer  User  ID,  Item  ID,  ValidatePurcha userId,  Integer  itemId,  String  Pricing string  seWS  fields) 

Runs  pricing  and  item  management  plug­ins  in  a  mock  purchase  for  the  given  user and item ID. 

validateMultiPurchase(Integer  User  ID,  Array  of  ValidatePurcha userId,  Integer  itemId,  String  Item ID  seWS  fields) 

Runs multiple mock purchases. 

  Payment API Methods  API Method 

Arguments 

Returns 

Description 

getPayment(Integer  paymentId) 

Payment ID 

PaymentWS 

Returns the payment for the given ID. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     66 

      getLatestPayment(Integer  userId) 

User ID 

PaymentWS 

getLastPayments(Integer  userId, Integer number) 

User  ID,  number  of  Integer  payments 

Returns  the  most  recent  payment  for  the  given user. 

Returns  the  last  N  payment  IDs  for  the  given user. 

getTotalRevenueByUser(Integ User ID  er userId) 

BigDecimal 

Returns  the  total  revenue  (payments  recieved) for the given user. 

getUserPaymentInstrument(Int User ID  eger userId) 

PaymentWS 

Returns  the  selected  "automatic  payment"  details for the given user. 

Limit,  PaymentWS 

Returns  an  array  of  paymentWS  between  the given range for the given user id. 

getUserPaymentsPage(Intege User  ID,  r  userId,  Integer  limit,  Integer  Offset  offset) 

createPayment(PaymentWS  payment) 

PaymentWS 

Integer 

Saves  the  given  payment  and  applies it to  the  user's  account  (as  per  configured  entity  preferences).  Does  not  process  the  payment, only creates it as 'Entered'. 

updatePayment(PaymentWS  payment) 

PaymentWS 

­ 

Updates  the  stored  payment  to  match  the  details  in  the  given  payment.  Given  payment must have an ID. 

deletePayment(Integer  paymentId) 

Payment ID 

­ 

Deletes the given payment. 

removePaymentLink(Integer  invoiceId, Integer paymentId) 

Invoice  Payment ID 

ID,  ­ 

Remove  the  link  between  a  payment  and  invoice (un­pay the invoice). 

removeAllPaymentLinks(Integ Payment ID  er paymentId) 

­ 

Removes  all the links between a payment  and invoice. 

ID,  ­ 

Link  the  payment  to  an  invoice  (pay  the  invoice). 

createPaymentLink(Integer  invoiceId, Integer paymentId) 

Invoice  Payment ID 

payInvoice(Integer invoiceId) 

Invoice ID 

PaymentAuthori Pays  the given invoice using the first credit  zationDTOEx  card available for the invoiced user. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     67 

      applyPayment(PaymentWS  payment, Integer invoiceId) 

PaymentWS,  Invoice ID 

processPayment(PaymentWS  PaymentWS,  payment, Integer invoiceId)  Invoice ID 

Integer 

Saves  the  given  payment  and  applies it to  the  given  invoice.  Does  not  process  the  payment, only creates it as 'Entered'. 

PaymentAuthori Saves  and  processes  the  payment,  zationDTOEx  applying  it  to  the  given  invoice.  If  no  payment  is  given,  the  payment  will  be  created  using  the  users  "automatic  payment"  instrument. If no invoice is given,  the  payment  will  be  applied  to  the  user's  account  according  to  the  configured  entity  preferences. 

validateCreditCard(com.sapie CreditCardDTO,  CardValidation nter.jbilling.server.entity.Credit ContactWS,  Level  WS  CardDTO  creditCard,  in number (1/2/3)  ContactWS contact, int level)       

Level  1  ­  Simple  checks  on  Credit  Card  Number, name, and mod10.  Level  2  ­  Address  and  Security  Code  validation.  Level 3 ­ Check number against a  payment gateway using pre­auth  transaction.    Returns object of CardValidationWS. 

  User API Methods  API Method 

Arguments 

Returns 

Description 

getUserWS(Integer userId) 

User ID 

UserWS 

Returns the user for the given ID. 

createUser(UserWS newUser)  UserWS 

Integer 

Creates  a  new  user  from  given  UserWS  object  &  returns  User  ID  of  the  created  user. 

updateUser(UserWS user) 

UserWS 

­ 

Updates  the  stored  user  details  to  match  the  given  user  object.  Given  user  must  have an ID. 

deleteUser(Integer userId) 

User ID 

­ 

Deletes the given user. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     68 

      getUserContactsWS(Integer  userId) 

User ID 

ContactWS 

Returns  all  contact  details  for  the  given  user. 

updateUserContact(Integer  User  ID,  Contact  ­  userId,  Integer  typeId,  Type  ID,  ContactWS contact)  ContactWS 

Updates  the  contact  details  of  the  given  user. 

getContactTypeWS(Integer  contactTypeId) 

ContactTypeW S 

Returns the contact type for the given ID. 

Integer 

Saves  the  given  contact  type  and  returns  the new ID. 

Contact Type ID 

createContactTypeWS(Contac ContactTypeWS  tTypeWS contactType) 

updateCreditCard(Integer  User  ID,  Credit  ­  userId,  CreditCardDTO  Card  creditCard) 

Updates the given users credit card data. 

updateAch(Integer  AchDTO ach) 

­ 

Updates  the  given  users  ACH  (automatic  clearing house) data. 

setAuthPaymentType(Integer  User  ID,  Payment  ­  userId,  Integer  Type, use type?  autoPaymentType,  boolean  use) 

Marks  the  users  Credit  Card  or  ACH  details  as  being  usable  for  automatic  payments. 

getAuthPaymentType(Integer  User ID  userId) 

Integer 

Returns  the  users  preferred  automatic  payment type. 

getUsersByStatus(Integer  statusId, boolean in) 

Status  ID,  in/  not  in  Integer  status 

If  "in"  true, returns a list of users who are in  the  givens  status,  if  false,  a  list  of  users  who are NOT in the given status. 

getUsersInStatus(Integer  statusId) 

Status ID 

Integer 

Array  of  user  IDs  who  are  in  the  given  status. 

getUsersNotInStatus(Integer  statusId) 

Status ID 

Integer 

Array  of  user  IDs  who  are  not  in  the given  status. 

getUsersByCustomField(Integ Type  ID,  Value  to  Integer  er typeId, String value)  match 

Array  of  user  IDs  who  have  a  custom  contact field with the given value. 

userId,  User ID, ACH 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     69 

      getUsersByCreditCard(String  Credit  number)  number 

Card  Integer 

Array  of  user  IDs  who  have  the  given  credit card ID. 

Integer 

Returns  the  user  id  for  the  given  user  name. 

saveCustomContactFields(Co ContactFieldType ntactFieldTypeWS fields)  WS 

­ 

Updates  the  available  custom  contact  fields for the system. 

processPartnerPayouts(Date  runDate) 

Run Date 

­ 

Runs  the  parter  payout  process  for  the  given date. 

getPartner(Integer partnerId) 

Patner ID 

PartnerWS 

Returns the partner for the given ID. 

getUserTransitions(Date  from,  Date range  Date to) 

UserTransition ResponseWS 

Returns  an  array of user transitions (status  changes) for the givend date range. 

getUserTransitionsAfterId(Inte ger id) 

UserTransition ResponseWS 

Returns  an  array of user transitions (status  changes) for the given user ID. 

getUserId(String username) 

create(UserWS  OrderWS order) 

User name 

User ID 

user,  UserWS, OrderWS  CreateRespons Saves  a  new  user  and  order  and  eWS  immediately  generates  a  new  invoice  for  the  created  user  and  order.  Returns  the  ID's of the created objects. 

saveCustomerNotes(Integer  userId, String notes) 

User ID, Notes 

­ 

Updates the given users notes. 

userExistsWithName(String  userName) 

 User Name 

Boolean 

Returns  true  if  a  user  exists  with the given  user name, false if not. 

userExistsWithId(Integer  userId) 

User ID 

Boolean 

Returns  true  if  a  user  with  the  given  ID  exists, false if not. 

getUserIdByEmail(String  email) 

Email ID 

Integer 

 

 

Retrieves  user  by  the  user's  email.  This  is  only  valid  if  Jbilling  is  configured  to  force  unique  emails  per  user/customers  in  the  company.  If  unique  emails  are  not  forced  then  an  exception  is  thrown  and  in  such  case  this  method  should  not  be  used. 

 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     70 

      Returns  user  ID  of  the  user  with  given  email. 

triggerPartnerPayoutProcess( Date runDate) 

Run Date 

­ 

Processes  partner  payouts  for  all  partners  that  have  a  payout  due  before  the  given  run date. 

processPartnerPayout(Integer  Partner ID  partnerId) 

­ 

Process  partner  payout  for  a  single  given  partner ID. 

createPartner(UserWS  UserWS,  newUser, PartnerWS partner)  PartnerWS 

Integer 

Creates  new  Partner  using  PartnerWS,  sets  meta  fields  values  from  UserWS  &  returns User Id. 

updatePartner(UserWS  UserWS,  newUser, PartnerWS partner)  PartnerWS 

­ 

Update  user  &  set  meta  fields  using  UserWS. Update partner using PartnerWS. 

deletePartner(Integer  partnerId) 

Partner ID 

­ 

Deletes  the  composed  Partner object from  the  system  by  first  deleting  the  associated  user and then deleting the Partner record. 

deleteCreditCard(Integer  userId) 

User ID 

­ 

Deletes  a  users  stored  credit  card  using  User  ID.  Payments  that  were  made  using  the deleted credit card will not be affected. 

deleteAch(Integer userId) 

User ID 

­ 

Deletes  a  users  stored  ACH  details  using  User  ID.  Payments  that  were  made  using  the  deleted  ACH  details  will  not  be  affected. 

Integer 

Returns  Auto  Payment  Type  using  User  ID. 

 

 

getAutoPaymentType(Integer  User ID  userId) 

setAutoPaymentType(Integer  User  ID,  Auto  ­  userId,  Integer  Payment  Type,  autoPaymentType,  boolean  Use  use) 

Set  Auto  Payment  Type  using  User  ID,  Auto Payment Type,  Use. 

      Copyright ©2013 Enterprise jBilling Software Ltd

 

     71 

     

Plans and Special Pricing API Methods  API Method 

Arguments 

Returns 

Description 

getPlanWS(Integer planId) 

Plan ID 

PlanWS 

Returns the plan for the given ID. 

createPlan(PlanWS plan) 

PlanWS 

Integer 

Save the given plan and return the new ID. 

updatePlan(PlanWS plan) 

PlanWS 

­ 

Update  the  stored  plan  details  to  match  the  given  plan  object.  Given  plan  must  have an ID. 

deletePlan(Integer planId) 

Plan ID 

­ 

Deletes the given plan. 

addPlanPrice(Integer  planId,  Plan  PlanItemWS price)  PlanItemWS 

ID,  ­ 

Adds a new price to the given plan. 

isCustomerSubscribed(Intege r planId, Integer userId) 

Plan ID, User ID 

boolean 

Returns true if the given user is subscribed  to the plan, false if not. 

getSubscribedCustomers(Inte ger planId) 

Plan ID 

Integer 

Returns  an  array  of  user  IDs  of  users who  have subscribed to the given plan. 

getPlansBySubscriptionItem(I nteger itemId) 

Item ID 

Integer 

Returns  a  list  of  plan  IDs  that  modify  customer  pricing  when  the  given  item  is  added to an order. 

getPlansByAffectedItem(Integ er itemId) 

Item ID 

Integer 

Returns  a  list  of  plan  IDs  that  affect  the  price of the given item. 

createCustomerPrice(Integer  User  userId, PlanItemWS planItem)  PlanItemWS 

ID,  PlanItemWS 

Creates  a  new  customer­specific  price  for  the  given  user.  This  new  price  will  only  affect the given user. 

updateCustomerPrice(Integer  User  userId, PlanItemWS planItem)  PlanItemWS 

ID,  ­ 

Updates  a  stored  customer­specific  price  with  the  details  of  the  given  price.  Price  object must have an ID. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     72 

      deleteCustomerPrice(Integer  userId, Integer planItemId) 

User  ID,  Plan  Item  ­  ID 

Deletes a customer­specific price. 

getCustomerPrices(Integer  userId) 

User ID 

PlanItemWS 

Returns  a  list  of  applied  pricing  (both  customer­specific  and  plan  prices)  for  the  given user. 

getCustomerPrice(Integer  userId, Integer itemId) 

User ID, Item ID 

PlanItemWS 

Returns  a  list  of  applied  pricing  (both  customer­specific  and  plan  prices)  for  the  given user and item. 

getCustomerPriceByAttributes User  ID,  Item  ID,  PlanItemWS  (Integer  userId,  Integer  itemId,  Map of attributes  Map attrs) 

Returns  a  list  of  applied  pricing  (both  customer­specific  and  plan  prices)  that  matches the given attributes. 

getCustomerPriceByWildcard User  ID,  Item  ID,  PlanItemWS @  Returns  a  list  of  applied  pricing  (both  Attributes(Integer  userId,  Map of attributes  customer­specific  and  plan  prices)  that  Integer  itemId,  Map attrs)  wildcards  for attribute values, where '*' can  mean "any value". 

getCallerId() 

­ 

Integer 

Returns  the  user  ID  of  the  authenticated  user account. 

getCallerCompanyId() 

­ 

Integer 

Returns  the  company  ID  authenticated user account. 

of 

the 

getCallerLanguageId() 

­ 

Integer 

Returns  the  language  ID  authenticated user account. 

of 

the 

getCallerCurrencyId() 

­ 

Integer 

Returns  the  currency  ID  authenticated user account. 

of 

the 

­ 

PlanWS 

Returns   list  of  plans   as   WS  objects,  or  an empty list if source list is empty. 

 

getAllPlans() 

      Copyright ©2013 Enterprise jBilling Software Ltd

 

     73 

     

Billing Process API Methods  API Method 

Arguments 

Returns 

Description 

isBillingRunning() 

­ 

boolean 

Returns  true  if  the  billing  process  is  currently running. 

triggerBillingAsync(Date  runDate) 

Run date 

­ 

Triggers  the  billing  process  for  the  given  date in a new thread (non­blocking). 

triggerBilling(Date runDate) 

Run date 

boolean 

Triggers  the  billing  process  for  the  given  date  in  the  current  thread  (blocking).  Returns  true  if  the  billing  process  was  triggered successfully, false if not. 

triggerAgeing(Date runDate) 

Run date 

­ 

Triggers the user ageing process. 

getBillingProcessConfiguratio n() 

­ 

BillingProcessC Returns the billing process configuration.  onfigurationWS 

createUpdateBillingProcessC BillingProcessConf Integer  onfiguration(BillingProcessCo igurationWS  nfigurationWS ws) 

Updates the current billing configuration. 

getBillingProcess(Integer  processId) 

Process ID 

BillingProcess WS 

Returns  the  outcome  of  the  given  billing  process. 

getLastBillingProcess() 

­ 

Integer 

Returns  the  billing  process  ID  of  the  last  run billing process. 

getOrderProcesses(Integer  orderId) 

Order ID 

List 

Returns  a  list  of  processes  that  have  added the given order into an invoice. 

getOrderProcessesByInvoice(I Invoice ID  nteger invoiceId) 

List 

Returns  a  list  of  processes  that  have  created or updated the given invoice. 

getReviewBillingProcess() 

BillingProcess WS 

Returns  the  outcome  of  the  latest  review  billing process. 

­ 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     74 

      setReviewApproval(Boolean  flag) 

boolean  is  review  BillingProcessC Approves  or  disapproves  the  latest review  approved  onfigurationWS  process.  Returns  the  billing  configuration  that generated the review. 

getBillingProcessGeneratedIn Process ID  voices(Integer processId) 

List 

Returns  a  list  of  invoice  IDs  generated  by  the given billing process. 

getAgeingConfiguration(Integ er languageId) 

AgeingWS 

Returns  a  list  of  ageing  steps  and  ageing  messages for the given language. 

Language ID 

saveAgeingConfiguration(Age AgeingWS  ,  Grace  ­  ingWS  steps,  Integer  Period,  Language  gracePeriod,  Integer  ID  languageId) 

Updates  the  current  ageing  configuration  with  the  given  ageing  steps  and  grace  period.  Ageing  notification  messages  will  be saved for the given language ID. 

isAgeingProcessRunning() 

­ 

Boolean 

Returns  true  if  the  ageing  process  is  currently  running  for  the  caller's  entity,  false if not. 

­ 

ProcessStatus WS 

Returns  the  status  of  the  last  run  (or  currently  running)  ageing  process.  That  the  ageing  process  currently  does  not  report  a  start  date, end date, or process id.  The  status  returned  by  this  method  will  only  report  the  RUNNING/FINISHED/FAILED  state  of  the  process. 

isBillingRunning(Integer  entityId) 

Entity ID 

Boolean 

Returns  true  if  the  Billing  Process  is  running for the given entity Id. 

getBillingProcessStatus() 

­ 

ProcessStatus WS 

Returns  the  status  of  the  last  run  (or  currently running) billing process. 

 

getAgeingProcessStatus()   

  Mediation Process API Methods  API Method 

Arguments 

Returns 

Description 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     75 

      triggerMediation() 

­ 

­ 

Triggers the mediation process. 

isMediationProcessing() 

­ 

boolean 

Returns  true  if  the  mediation  process  is  currently running. 

getAllMediationProcesses() 

­ 

List 

Returns  a  list  of  all  mediation  process  outcomes. 

getMediationEventsForOrder(I Order ID  nteger orderId) 

List 

Returns  a list of mediation events (external  data read in) for the given order. 

getMediationEventsForInvoice Invoice ID  (Integer invoiceId) 

List 

Returns  a list of mediation events (external  data read in) for the given invoice. 

getMediationRecordsByMedia Mediation  Process  List  mediationProcessId) 

Returns  a  list  of  mediation  records  for  the  given process. 

getNumberOfMediationRecor dsByStatuses() 

Returns  a  breakdown  of  the  mediation  process by record status. 

­ 

List 

getAllMediationConfigurations ­  () 

List 

createMediationConfiguration (MediationConfigurationWS  cfg) 

­ 

MediationConfigur ationWS 

Saves a new mediation configuration. 

updateAllMediationConfigurat List configurations) 

Updates  all  given  mediation  configurations.  Given  configs  must  have  an ID. 

deleteMediationConfiguration (Integer cfgId) 

­ 

Deletes the given mediation configuration. 

Integer 

Triggers  the  mediation  process  for  a  specific  configuration  and  returns  the 

Configuration ID 

triggerMediationByConfigurati Mediation  on(Integer cfgId)  Configuration ID      Copyright ©2013 Enterprise jBilling Software Ltd

 

     76 

      mediation  process  id  of  the  running  process. 

isMediationProcessRunning()  ­ 

Boolean 

Returns  true  if  a  running  Mediation  Process  exists  for  the  given  entity  id.  A  process  is  considered  to  be  running  if  it  does not have an end time, false if not. 

ProcessStatus WS 

Returns  the  status  of  the  last  run  (or  currently running) mediation process. 

 

getMediationProcessStatus() 

­ 

 

getMediationProcess(Integer  mediationProcessId) 

Mediation  Process  MediationProce Returns  the  mediation  process  for  the  ID  ssWS  given process id or null if not found. 

Provisioning Process API Methods  API Method 

Arguments 

Returns 

Description 

triggerProvisioning() 

­ 

­ 

Triggers the provisioning process. 

updateOrderAndLineProvisio Order  ID,  Order  ­  ningStatus(Integer  inOrderId,  Line ID, Result  Integer inLineId, String result) 

Updates  the  order  or  line  provisioning  status  to  the  set  result  (either  "fail",  "unavailable" or "success"). 

updateLineProvisioningStatus Order  Line  (Integer  orderLineId,  Integer  Status ID  provisioningStatus) 

Updates the order line provisioning status. 

ID,  ­ 

  Preference API Methods  API Method 

Arguments 

Returns 

Description 

updatePreferences(Preferenc eWS prefList) 

PreferenceWS 

­ 

Stores all the given preference values. 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     77 

      updatePreference(Preference WS preference) 

PreferenceWS 

­ 

Stored the given preference value. 

getPreference(Integer  preferenceTypeId) 

Preference Type ID  PreferenceWS 

Returns  the  preference  for  the  given  preference type id. 

getCurrencies() 

­ 

CurrencyWS 

Returns a list of configured currencies. 

updateCurrencies(CurrencyW CurrencyWS  S currencies) 

­ 

Stores all the given currency values. 

updateCurrency(CurrencyWS  CurrencyWS  currency) 

­ 

Updates  the  given  currency.  Storing  the  exchange  rate,  system  rate,  and  currency  availability. 

createCurrency(CurrencyWS  currency) 

CurrencyWS 

Integer 

Saves a new currency type and returns the  new ID. 

getCompany() 

­ 

CompanyWS 

Returns  the  company  contact  details  for  the API users company. 

updateCompany(CompanyW S companyWS) 

CompanyWS 

­ 

Updates  the  company  contact  details  for  the API users company. 

createUpdateNotification(Inte Mesage  ID  ,  ­  ger  messageId,  MessageDTO  MessageDTO@  dto) 

Saves  or  updates  an  existing  notification  message. 

    Plug­in API Methods    API Method 

Arguments 

Returns 

Description 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     78 

      getPluginWS(Integer pluginId)  Plugin ID 

PluggableTask WS 

Returns  the  configured  plug­in  for  the  given ID. 

createPlugin(PluggableTask WS plugin) 

PluggableTaskWS  Integer 

Saves  the  given  plugin  and  returns  the  new ID. 

updatePlugin(PluggableTask WS plugin) 

PluggableTaskWS  ­ 

Updates  the  stored  plugin.  Given  plugin  must have an ID. 

deletePlugin(Integer plugin) 

Integer 

­ 

Deletes the given plugin 

Returns 

Description 

­ 

This  method  reschedules  an  existing  scheduled  task  that  got  changed.  If  not  existing,  the  new  plugin  may  need  to  be  scheduled  only  if  it  is  an  instance  of  IscheduledTask. 

 

Quartz Job API Methods    API Method 

Arguments 

rescheduleScheduledPlugin(I Plugin ID  nteger pluginId) 

  Appendix A  Constants Reference  Language Codes  Code 

Name 

1 

English 

2 

Portuguese 

Currency Codes  Code 

Currency Name  ISO Code 

Symbol 

Country 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     79 

      1 

United States Dollar  USD 

US$ 

USA 

2 

Canadian Dollar 

CAD 

C$ 

Canada 

3 

Euro 

EUR 

€ 

Europe 

4 

Yen 

JPY 

� 

Japan 

5 

Pound Sterling 

GBP 

� 

United Kingdom 

6 

South Korean Won 

KRW 

  

South Korea 

7 

Swiss Franc 

CHF 

Sf 

Switzerland 

8 

Swedish Krona 

SEK 

SeK 

Sweden 

9 

Singapore Dollar 

SGD 

S$ 

Singapore 

10 

Ringgit 

MYR 

M$ 

Malaysia 

11 

Australian Dollar 

AUD 

$ 

Australia 

Role Codes  Code 

Meaning 

1 

Internal 

2 

Super User 

3 

Clerk 

4 

Partner 

5 

Customer 

User Status Codes  Code 

Meaning 

1 

Active 

2 

Overdue 

3 

Overdue 2 

4 

Overdue 3 

5 

Suspended 

6 

Suspended 2 

7 

Suspended 3 

8 

Deleted 

Subscriber Status Codes  Code 

Meaning 

1 

Active 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     80 

      2 

Pending Subscription 

3 

Unsubscribed 

4 

Pending Expiration 

5 

Expired 

6 

Nonsubscriber 

7 

Discontinued 

Payment Method Codes  Code 

Meaning 

1 

Cheque 

2 

Visa 

3 

MasterCard 

4 

AMEX 

5 

ACH/CCA 

6 

Discovery 

7 

Diners 

8 

PayPal 

Order Status Codes  Code 

Meaning 

1 

Active 

2 

Finished 

3 

Suspended 

4 

Suspended (auto) 

Order Billing Type Codes  Code 

Meaning 

1 

Pre­paid 

2 

Post­paid 

Order Line Type Codes  Code 

Meaning 

1 

Item 

    Copyright ©2013 Enterprise jBilling Software Ltd

 

     81 

      2 

Tax 

3 

Penalty 

Invoice Status Codes  Code 

Meaning 

1 

Paid 

2 

Unpaid 

3 

Unpaid, balance carried to a new invoice. 

Period units (units of time)  Unit 

Meaning 

1 

Month 

2 

Week 

3 

Day 

4 

Year 

Payment results  Code 

Meaning 

1 

Successful 

2 

Failed 

3 

Payment gateway not available 

4 

Manually entered (payment gateway not involved, such  as a cheque). 

  Dynamic Balance Codes  Code 

Meaning 

1 

No dynamic balance 

2 

Pre paid 

3 

Credit limit 

Provisioning Status Codes      Copyright ©2013 Enterprise jBilling Software Ltd

 

     82 

     

Code 

Meaning 

1 

Active 

2 

Inactive 

3 

Pending Active 

4 

Pending Inactive 

5 

Failed 

6 

Unavailable 

Automatic Payment Type  Code 

Meaning 

1 

Credit Card 

2 

ACH 

3 

Cheque 

Invoice Delivery Method  Code 

Meaning 

1 

Email 

2 

Paper 

3 

Both Email & Paper 

Appendix B  How to use the jBilling 3 Logs for integration  The  jBilling  3  logs   are  located  at  logsjbilling.log.  The  logs   will  contain  debug statements   at  the  entry   and  exit  of  certain  API  method  calls.  These  debug  statements   at  entry   and  exit  of  API  method  calls,  specifically,  from  the  Web  Services   API  calls   can  be  quite  useful  for  developers who can use this additional information for integration of other systems with jBilling 3.  For  example,  take  a look  at the below snapshot from jbilling.loglogs.    The below snapshot  is an output after submitting on the 'Create Order' page of jBilling 3.  2011­07­20 17:02:08,660 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to createOrder  returning: 107900  2011­07­20 17:02:09,280 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getOrder  parameters: [107900]      Copyright ©2013 Enterprise jBilling Software Ltd

 

     83 

      2011­07­20 17:02:12,103 DEBUG  [com.sapienter.jbilling.server.invoice.InvoiceBL] converstion 0  2011­07­20 17:02:12,103 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to getOrder  returning: OrderWS{id=107900, userId=10790, currencyId=1, activeUntil=null,  activeSince=2011­07­20 00:00:00.0, isCurrent=1, statusStr='Active',  periodStr='Monthly', periodId=2, billingTypeStr='pre paid',  lines=[OrderLineWS{id=208100, amount='10.0000000000', quantity='1.0000000000',  price='10.0000000000', deleted=0, description='Long distance call ­ Generic',  useItem=false, itemId=2900, typeId=1}]}  2011­07­20 17:02:12,163 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getUserWS  parameters: [10790]  2011­07­20 17:02:12,227 DEBUG  [com.sapienter.jbilling.server.util.PreferenceBL] Looking for preference 43,  for entity 1 and table 'entity'  2011­07­20 17:02:12,265 DEBUG  [com.sapienter.jbilling.server.util.PreferenceBL] Looking for preference 43,  for entity 1 and table 'entity' 

The  Web  Services  API that is  exposed for integration of jBilling with external systems  is  used as   an  inline  Java  API  for  making  the  same  transactions   that  are  supported  via  API,  which  has   become extensive and fully functional in jBilling 3.  Let  us  take another example of using the logs  to understanding the integration API calls  that may   be required for example, to make a Payment.  The steps required on the GUI for making a Payment are as follows:  1. List Invoices by clicking on 'Invoices' link in the main menu  2. Select  an Invoice from the list of Invoices  (The selected Invoice details  are displayed on  the right hand side)  3. Click on 'Pay Invoice'  4. Choose a Payment option  5. Confirm and Submit  Suppose  we  have  performed  above  actions   on  the  GUI,  there  are  certain  parts   in  the  log  trace  that I'd like to highlight for each of the above steps.  2011­07­20 17:21:37,406 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getInvoiceWS  parameters: [70]  2011­07­20 17:21:37,415 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to getInvoiceWS  returning: InvoiceWS [balance=20.0000000000, carriedBalance=0E­10,  createDateTime=2007­07­26 00:00:00.0, createTimeStamp=2007­07­26 18:17:19.113,  currencyId=1, customerNotes=null, delegatedInvoiceId=null, deleted=0,      Copyright ©2013 Enterprise jBilling Software Ltd

 

     84 

      dueDate=2007­08­26 00:00:00.0, id=70, inProcessPayment=1, invoiceLines=[{id=67  description=Lemonade ­ all you can drink monthly amount=20.0000000000  price=20.0000000000 quantity=1.0000000000 deleted=0 itemId=2  sourceUserId=10743 isPercentage=0}], isReview=0, lastReminder=null, number=11,  orders=[], overdueStep=null, paymentAttempts=0, payments=[],  statusDescr=Unpaid, statusId=2, toProcess=1, total=20.0000000000,  userId=10743]  2011­07­20 17:21:37,420 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getUserWS  parameters: [10743] 

Select a particular Invoice (70), API Call getInvoiceWS()  2011­07­20 17:21:37,572 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to getUserWS  returning: UserWS [ach=null, autoRecharge=0E­10, automaticPaymentType=1,  balanceType=1, blacklistMatches=[], childIds=[], companyName=Prancing Pony,  contact=ContactWS{id=112603, type=null, title='null', lastName='Baggins',  firstName='Frodo', initial='null', organization='null', address1='null',  address2='null', city='null', stateProvince='null', postalCode='null',  countryCode='null', phone='', fax='', email='[email protected]', type='null',  include='1'}, createDatetime=2009­10­30 00:00:00.0, creditCard=null,  creditLimit=0E­10, currencyId=1, customerId=1067, deleted=0,  dueDateUnitId=null, dueDateValue=null, dynamicBalance=0E­10,  excludeAgeing=false, failedAttempts=0, id=10743, invoiceChild=false,  invoiceDeliveryMethodId=null, isParent=false, language=English, languageId=1,  lastLogin=null, lastStatusChange=null, mainOrderId=null, mainRoleId=5,  nextInvoiceDate=null, notes=null, owingBalance=20.0000000000, parentId=null,  partnerId=null, password=46f94c8de14fb36680850768ff1b7f2a, role=Customer,  status=Active, statusId=1, subscriberStatusId=6, userIdBlacklisted=false,  userName=carry­over­test1]  2011­07­20 17:21:37,576 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to  getTotalRevenueByUser parameters: [10743]  2011­07­20 17:21:37,587 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to  getTotalRevenueByUser returning: 0  2011­07­20 17:21:37,827 DEBUG  [com.sapienter.jbilling.server.util.PreferenceBL] Looking for preference 20,  for entity 1 and table 'entity'  2011­07­20 17:22:27,422 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getUserWS  parameters: [10743]  2011­07­20 17:22:27,512 DEBUG [com.sapienter.jbilling.server.user.ContactBL]  ContactDTO: getting custom fields  2011­07­20 17:22:27,516 DEBUG [com.sapienter.jbilling.server.user.ContactBL]  Returning dto with 3 fields  2011­07­20 17:22:27,516 DEBUG      Copyright ©2013 Enterprise jBilling Software Ltd

 

     85 

      [com.sapienter.jbilling.server.util.api.APILogger] Done call to getUserWS  returning: UserWS [ach=null, autoRecharge=0E­10, automaticPaymentType=1,  balanceType=1, blacklistMatches=[], childIds=[], companyName=Prancing Pony,  contact=ContactWS{id=112603, type=null, title='null', lastName='Baggins',  firstName='Frodo', initial='null', organization='null', address1='null',  address2='null', city='null', stateProvince='null', postalCode='null',  countryCode='null', phone='', fax='', email='[email protected]', type='null',  include='1'}, createDatetime=2009­10­30 00:00:00.0, creditCard=null,  creditLimit=0E­10, currencyId=1, customerId=1067, deleted=0,  dueDateUnitId=null, dueDateValue=null, dynamicBalance=0E­10,  excludeAgeing=false, failedAttempts=0, id=10743, invoiceChild=false,  invoiceDeliveryMethodId=null, isParent=false, language=English, languageId=1,  lastLogin=null, lastStatusChange=null, mainOrderId=null, mainRoleId=5,  nextInvoiceDate=null, notes=null, owingBalance=20.0000000000, parentId=null,  partnerId=null, password=46f94c8de14fb36680850768ff1b7f2a, role=Customer,  status=Active, statusId=1, subscriberStatusId=6, userIdBlacklisted=false,  userName=carry­over­test1]  2011­07­20 17:22:27,521 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getUnpaidInvoices  parameters: [10743]  2011­07­20 17:22:27,714 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to  getUnpaidInvoices returning: [70]  2011­07­20 17:22:27,717 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getInvoiceWS  parameters: [70]  2011­07­20 17:22:27,726 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to getInvoiceWS  returning: InvoiceWS [balance=20.0000000000, carriedBalance=0E­10,  createDateTime=2007­07­26 00:00:00.0, createTimeStamp=2007­07­26 18:17:19.113,  currencyId=1, customerNotes=null, delegatedInvoiceId=null, deleted=0,  dueDate=2007­08­26 00:00:00.0, id=70, inProcessPayment=1, invoiceLines=[{id=67  description=Lemonade ­ all you can drink monthly amount=20.0000000000  price=20.0000000000 quantity=1.0000000000 deleted=0 itemId=2  sourceUserId=10743 isPercentage=0}], isReview=0, lastReminder=null, number=11,  orders=[], overdueStep=null, paymentAttempts=0, payments=[],  statusDescr=Unpaid, statusId=2, toProcess=1, total=20.0000000000,  userId=10743] 

Click   'Pay   Invoice',  behind  the  scenes   API  Calls   like  getUserPaymentInstrument(),  getUnpaidInvoices() etc.  2011­07­20 17:22:27,731 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to  getUserPaymentInstrument parameters: [10743]  2011­07­20 17:22:27,819 DEBUG  [com.sapienter.jbilling.server.pluggableTask.admin.PluggableTaskManager] total  classes = 1      Copyright ©2013 Enterprise jBilling Software Ltd

 

     86 

      2011­07­20 17:22:27,819 DEBUG  [com.sapienter.jbilling.server.pluggableTask.admin.PluggableTaskManager]  Applying task com.sapienter.jbilling.server.pluggableTask.BasicPaymentInfoTask  2011­07­20 17:22:27,951 DEBUG  [com.sapienter.jbilling.server.pluggableTask.BasicPaymentInfoTask] Could not  find payment instrument for user 10743  2011­07­20 17:22:27,951 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to  getUserPaymentInstrument returning: null  2011­07­20 17:23:09,081 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getUserWS  parameters: [10743]  2011­07­20 17:23:09,112 DEBUG  [com.sapienter.jbilling.server.util.PreferenceBL] Looking for preference 43,  for entity 1 and table 'entity'  2011­07­20 17:23:09,119 DEBUG  [com.sapienter.jbilling.server.util.PreferenceBL] Looking for preference 43,  for entity 1 and table 'entity'  2011­07­20 17:23:09,170 DEBUG  [com.sapienter.jbilling.server.payment.tasks.PaymentFilterTask] UserIdFilter  enabled  2011­07­20 17:23:09,170 DEBUG  [com.sapienter.jbilling.server.payment.tasks.PaymentFilterTask] NameFilter  enabled  2011­07­20 17:23:09,170 DEBUG  [com.sapienter.jbilling.server.payment.tasks.PaymentFilterTask]  CreditCardFilter enabled  2011­07­20 17:23:09,170 DEBUG  [com.sapienter.jbilling.server.payment.tasks.PaymentFilterTask] AddressFilter  enabled  2011­07­20 17:23:09,170 DEBUG  [com.sapienter.jbilling.server.payment.tasks.PaymentFilterTask]  IpAddressFilter enabled  2011­07­20 17:23:09,170 DEBUG  [com.sapienter.jbilling.server.payment.tasks.PaymentFilterTask] PhoneFilter  enabled  2011­07­20 17:23:09,226 DEBUG [com.sapienter.jbilling.server.user.ContactBL]  ContactDTO: getting custom fields  2011­07­20 17:23:09,232 DEBUG [com.sapienter.jbilling.server.user.ContactBL]  Returning dto with 3 fields  2011­07­20 17:23:09,232 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to getUserWS  returning: UserWS [ach=null, autoRecharge=0E­10, automaticPaymentType=1,  balanceType=1, blacklistMatches=[], childIds=[], companyName=Prancing Pony,  contact=ContactWS{id=112603, type=null, title='null', lastName='Baggins',  firstName='Frodo', initial='null', organization='null', address1='null',  address2='null', city='null', stateProvince='null', postalCode='null',  countryCode='null', phone='', fax='', email='[email protected]', type='null',      Copyright ©2013 Enterprise jBilling Software Ltd

 

     87 

      include='1'}, createDatetime=2009­10­30 00:00:00.0, creditCard=null,  creditLimit=0E­10, currencyId=1, customerId=1067, deleted=0,  dueDateUnitId=null, dueDateValue=null, dynamicBalance=0E­10,  excludeAgeing=false, failedAttempts=0, id=10743, invoiceChild=false,  invoiceDeliveryMethodId=null, isParent=false, language=English, languageId=1,  lastLogin=null, lastStatusChange=null, mainOrderId=null, mainRoleId=5,  nextInvoiceDate=null, notes=null, owingBalance=20.0000000000, parentId=null,  partnerId=null, password=46f94c8de14fb36680850768ff1b7f2a, role=Customer,  status=Active, statusId=1, subscriberStatusId=6, userIdBlacklisted=false,  userName=carry­over­test1]  2011­07­20 17:23:09,235 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getUnpaidInvoices  parameters: [10743]  2011­07­20 17:23:09,246 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to  getUnpaidInvoices returning: [70]  2011­07­20 17:23:09,249 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to getInvoiceWS  parameters: [70]  2011­07­20 17:23:09,273 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to getInvoiceWS  returning: InvoiceWS [balance=20.0000000000, carriedBalance=0E­10,  createDateTime=2007­07­26 00:00:00.0, createTimeStamp=2007­07­26 18:17:19.113,  currencyId=1, customerNotes=null, delegatedInvoiceId=null, deleted=0,  dueDate=2007­08­26 00:00:00.0, id=70, inProcessPayment=1, invoiceLines=[{id=67  description=Lemonade ­ all you can drink monthly amount=20.0000000000  price=20.0000000000 quantity=1.0000000000 deleted=0 itemId=2  sourceUserId=10743 isPercentage=0}], isReview=0, lastReminder=null, number=11,  orders=[], overdueStep=null, paymentAttempts=0, payments=[],  statusDescr=Unpaid, statusId=2, toProcess=1, total=20.0000000000,  userId=10743] 

Make a payment, API Call applyPayment()  2011­07­20 17:23:14,077 DEBUG  [grails.app.controller.jbilling.PaymentController] creating payment  PaymentWS{id=0, baseUserId=null, paymentMethodId=1, method='null',  amount='20.00', balance='null', isRefund=0, isPreauth=null, paymentDate=Wed  Jul 20 00:00:00 IST 2011, deleted=0} for invoice 70  2011­07­20 17:23:14,077 DEBUG  [grails.app.controller.jbilling.PaymentController] creating payment  PaymentWS{id=0, baseUserId=null, paymentMethodId=1, method='null',  amount='20.00', balance='null', isRefund=0, isPreauth=null, paymentDate=Wed  Jul 20 00:00:00 IST 2011, deleted=0} for invoice 70  2011­07­20 17:23:14,077 DEBUG  [grails.app.controller.jbilling.PaymentController] entering payment  2011­07­20 17:23:14,077 DEBUG  [grails.app.controller.jbilling.PaymentController] entering payment      Copyright ©2013 Enterprise jBilling Software Ltd

 

     88 

      2011­07­20 17:23:14,078 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Call to applyPayment  parameters: [PaymentWS{id=0, baseUserId=null, paymentMethodId=1,  method='null', amount='20.00', balance='null', isRefund=0, isPreauth=null,  paymentDate=Wed Jul 20 00:00:00 IST 2011, deleted=0}, 70]  2011­07­20 17:23:14,147 DEBUG  [com.sapienter.jbilling.server.util.db.JbillingTableDAS] Looking for table +  payment  2011­07­20 17:23:14,151 DEBUG  [com.sapienter.jbilling.server.payment.PaymentSessionBean] applying payment to  invoice 70  2011­07­20 17:23:14,152 DEBUG  [com.sapienter.jbilling.server.payment.PaymentSessionBean] Set invoice balance  to: 0  2011­07­20 17:23:14,216 DEBUG  [com.sapienter.jbilling.server.pluggableTask.admin.PluggableTaskManager] total  classes = 1  2011­07­20 17:23:14,216 DEBUG  [com.sapienter.jbilling.server.pluggableTask.admin.PluggableTaskManager]  Applying task com.sapienter.jbilling.server.process.task.BasicAgeingTask  2011­07­20 17:23:14,320 DEBUG  [com.sapienter.jbilling.server.invoice.InvoiceBL] user with invoice:70  2011­07­20 17:23:14,320 DEBUG  [com.sapienter.jbilling.server.invoice.InvoiceBL] user with overdue: true  2011­07­20 17:23:14,320 DEBUG  [com.sapienter.jbilling.server.process.task.BasicAgeingTask] User 10743 still  has overdue invoices, cannot remove from ageing.  2011­07­20 17:23:14,323 DEBUG  [com.sapienter.jbilling.server.system.event.EventManager] processing event  PaymentSuccessfulEvent{paymentId=1900, amount=20.00}  2011­07­20 17:23:14,323 DEBUG  [com.sapienter.jbilling.server.system.event.InternalEventProcessor] In  InternalEventProcessor::process()  2011­07­20 17:23:14,346 DEBUG  [com.sapienter.jbilling.server.pluggableTask.admin.PluggableTaskManager] total  classes = 8  2011­07­20 17:23:14,346 DEBUG  [com.sapienter.jbilling.server.system.event.InternalEventProcessor] Processing  PaymentSuccessfulEvent{paymentId=1900, amount=20.00} with  com.sapienter.jbilling.server.user.balance.DynamicBalanceManagerTask@7fa58648  2011­07­20 17:23:14,346 DEBUG  [com.sapienter.jbilling.server.user.balance.DynamicBalanceManagerTask] Nothing  to update  2011­07­20 17:23:14,347 DEBUG  [com.sapienter.jbilling.server.system.event.EventManager] Now processing with  com.sapienter.jbilling.server.user.event.SubscriptionStatusEventProcessor  2011­07­20 17:23:14,355 DEBUG  [com.sapienter.jbilling.server.pluggableTask.admin.PluggableTaskManager] total      Copyright ©2013 Enterprise jBilling Software Ltd

 

     89 

      classes = 1  2011­07­20 17:23:14,355 DEBUG  [com.sapienter.jbilling.server.pluggableTask.admin.PluggableTaskManager]  Applying task  com.sapienter.jbilling.server.user.tasks.BasicSubscriptionStatusManagerTask  2011­07­20 17:23:14,370 DEBUG  [com.sapienter.jbilling.server.system.event.EventManager] Now processing with  com.sapienter.jbilling.server.payment.event.GatewayAlarmEventProcessor  2011­07­20 17:23:14,370 DEBUG  [com.sapienter.jbilling.server.util.api.APILogger] Done call to applyPayment  returning: 1900 

Finally,  check   the entry  'Done call to applyPayment returning: 1900', where database 1900 is   the ID of the Payment created in the system.  These  behind  the  scenes   API  calls   and  their  sequence  of  invocations   show  the  API  calls   that  may   have  to  be  performed  for  performing  similar  actions   from  a  third  party   system  like  a  CRM  system for a similar action on jBilling.  Similarly,  logs   can  be  used  to  check   the  API  calls   required  for  other  actions   that  can  be  mimicked by performing similar actions on the GUI.   

Revision History  Date 

Author 

Version  Description 

07/26/2013 

Mahesh Shivarkar 

1.0 

Received document for updation of new API methods.  

07/30/2013 

Mahesh Shivarkar 

1.1 

Copied existing API reference from the document to the  integration guide under Web­Services API reference  section.. 

07/31/2013 

Mahesh Shivarkar 

1.2 

Added missing API references from release 3.2 in the  Integration Guide.  

08/02/2013 

Mahesh Shivarkar 

1.3 

Validated all constants available in the document,  found all are correct. Added missing constant.  

08/07/2013 

Mahesh Shivarkar 

1.4 

Validated object references. Added missing fields of the  objects & their behaviours, corrected some objects  properties & their descriptions. Removed unused  properties.   

08/29/2013 

Mahesh Shivarkar 

1.5 

Completed pending fields descriptions of the objects.  Added Revision History table. 

      Copyright ©2013 Enterprise jBilling Software Ltd

 

     90