Using the Kill Bill Java client

Kill Bill provides a Java client that can be used to invoke Kill Bill’s API methods. This document is aimed at providing a detailed walkthrough of how to set up this client and use it to execute Kill Bill API methods.

Pre-requisites

You have gone through the Getting started tutorial and have Kill Bill, Kaui and the database setup and running
You have a tenant configured with API key bob and API secret lazar

Setting up the Kill Bill Java client

The first step in setting up the Kill Bill Java client is to add the following Maven dependency related to the Kill Bill client to your POM file. (You can find out the latest version number of the library from its README file)

 <dependency>
  <groupId>org.kill-bill.billing</groupId>
  <artifactId>killbill-client-java</artifactId>
  <version>... release version ...</version>
 </dependency>

Writing the Java code

Once the dependency is added, you can write code that invokes the Kill Bill APIs as shown below.

 public void testGetPaymentMethods() throws KillBillClientException {
  int default_connection_timeout_sec = 10;
  int default_read_timeout_sec = 60;
  int default_request_timeout_sec = default_read_timeout_sec;
  String username = "admin";
  String password = "password";
  String apiKey = "bob";
  String apiSecret = "lazar";
  String serverHost = "localhost";
  int serverPort = 8080;
  String kbServerUrl = String.format("http://%s:%d", serverHost, serverPort);
  KillBillHttpClient killBillHttpClient = new KillBillHttpClient(kbServerUrl, username, password, apiKey,apiSecret, null, null, default_connection_timeout_sec * 1000, default_read_timeout_sec * 1000,default_request_timeout_sec * 1000);
  AccountApi accountApi = new AccountApi(killBillHttpClient);
  String createdBy = "Kill Bill Client Tutorial";
  String reason = "Demonstrating Kill Bill Client";
  String comment = "Demonstrating Kill Bill Client";
  RequestOptions requestOptions =  RequestOptions.builder().withCreatedBy(createdBy).withReason(reason).withComment(comment).build();
  Map<String, String> NULL_PLUGIN_PROPERTIES = null;
  UUID accountId = UUID.fromString("a21f1ca3-53ec-456b-8039-7170350c9c12"); //accountId whose payment methods are to be fetched, replace with appropriate accountId from your database
  List<PaymentMethod> paymentMethods = accountApi.getPaymentMethodsForAccount(accountId, NULL_PLUGIN_PROPERTIES,requestOptions);
  logger.info("Payment methods=" + paymentMethods.size());
 }

This code first declares and initializes some variables like username, password and so on.
Next, a KillBillHttpClient instance is created using these variables.
After that, the code creates an AccountApi instance using the killBillHttpClient object. AccountApi can be used to execute account related Kill Bill methods. Just like AccountApi, the org.killbill.billing.client.api.gen package has other classes like PaymentMethodApi, OverDueApi which can be used to invoke the corresponding API methods.
Next, the code declares and initializes some more variables like createdBy, reason and comment.
A RequestOptions instance is then created using these variables.
Finally, the code invokes the AccountApi#getPaymentMethodsForAccount method. This returns the payment methods corresponding to the specified accountId.

Executing the code

In order to execute this code, you need to ensure Kill Bill is running (either on AWS or via Docker or in Tomcat) or standalone and execute the code specified above.

TroubleShooting

This section lists some troubleshooting tips which can be useful to identify/fix errors.

Using KillBillClientException

The code above specifies a KillBillClientException in the throws clause. This exception is typically thrown in case there is an error in executing an API method. It can be used to obtain an error code which provides more information about the error.

The following code demonstrates how this exception can be used:

 List<PaymentMethod> paymentMethods = null;
 try {
  paymentMethods =  accountApi.getPaymentMethodsForAccount(accountId, NULL_PLUGIN_PROPERTIES,requestOptions);
 } catch (KillBillClientException e) {
  int errorCode = e.getBillingException().getCode();
  if(errorCode == ErrorCode.ACCOUNT_DOES_NOT_EXIST_FOR_ID.getCode())   {
   logger.info(accountId+" does not exist");
 }

The catch block retrieves the error code from the KillBillClientException
This errorCode can then compared with the error codes defined in the ErrorCode class. The code above compares it with ACCOUNT_DOES_NOT_EXIST_FOR_ID and logs an error message accordingly.

More about errors

The KillBillClientException is only thrown when the server returns a 400, 401, 409, 500, etc error. If there is no response (204) or if an object cannot be found (404), the code returns a null (for single objects) or an empty list (for collections of objects).

Kill Bill logs

The Kill Bill logs can also be useful while troubleshooting as they can provide additional information about the error. The Kill Bill log files can be configured as explained here.

Debugging the code

Finally, it may also be useful to set a break point and debug the code in order to identify the issue. The steps for this are explained here.

Using the sample code

The complete source code used in this example is available at this Github location. You can clone it in order to get started with your application. For detailed instructions on how to set up the code in Eclipse IDE, you can refer to our development document.

PreviousPrev NextNext