Kill Bill provides built-in support for Swagger UI. Swagger UI allows viewing and interacting with Kill Bill’s API without having to write any code. This can be very useful for debugging. This document is aimed at providing a detailed walkthrough of how to set up and use Kill Bill’s Swagger documentation.

To know more about Kill Bill’s Swagger UI Integration, you can refer to this Github page.

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

View API Methods

In order to view Kill Bill API methods in Swagger UI, you need to do the following:

  1. Ensure that Kill Bill is running (either on AWS or via Docker or in Tomcat) or standalone

  2. Type <KILL_BILL_HOME>/api.html in a browser. (Replace <KILL_BILL_HOME> with your Kill Bill home URL, so if Kill Bill is deployed at 127.0.0.1:8080, you can use http://127.0.0.1:8080/api.html). This displays all Kill Bill’s API methods as follows:

swagger ui home

  1. You can expand any API method to know more about it simply by clicking it. For example, to retrieve all the payment methods related to an account you can click on /1.0/kb/accounts/{accountId}/paymentMethods which displays the following:

retrieve account payment methods

The top section (red box) indicates the method’s parameters while the bottom section (blue box) indicates the valid responses.

Authorization

Swagger UI allows executing an API method. Before executing any API method, the authorization information needs to be entered as explained below. This needs to be done only once.

  1. Click the Authorize button in the top right corner. This displays the following screen:

swagger ui authorization

  1. In the Basic Authorization section, enter the username as admin and password as password. Click Authorize as follows:

basic authorization

  1. In the Killbill Api Key section, enter the value as bob and click Authorize:

kill bill api key

  1. In the Killbill Api Secret section, enter the value as lazar and click Authorize

kill bill api secret

Execute a GET API method

Swagger UI can now be used to execute any API method. This section explains how you can execute a GET API method.

Suppose you would like to execute the /1.0/kb/accounts/{accountId}/paymentMethods method to retrieve all the payment methods associated with an account. You need to do the following:

  1. Click on the /1.0/kb/accounts/{accountId}/paymentMethods method. This expands the method as follows:

retrieve account payment methods2

  1. Click on Try it Out. This displays the following screen:

retrieve account payment method execution

  1. Enter values for parameters as follows:

    • accountId - The account whose payment methods are to be retrieved (example - a21f1ca3-53ec-456b-8039-7170350c9c12)

    • withPluginInfo - Optional, defaults to false, indicating that plugin info should not be retrieved

    • includedDeleted - Optional, defaults to false, indicating that deleted payment methods should not be included

    • pluginProperty - Optional, can be used to specify plugin properties

    • audit - Optional, defaults to NONE, indicating that audit information should not be returned

retrieve account payment method execution2

  1. Click Execute. This displays the following screen:

retrieve account payment method output

So, all the payment methods associated with the specified accountId are returned.

Execute a POST API method

This section explains how you can execute a POST API method.

Suppose you would like to execute the /1.0/kb/accounts/{accountId}/payments method to trigger a payment.

You need to do the following:

  1. Click on the /1.0/kb/accounts/{accountId}/payments method. This expands the method as follows:

trigger payment

  1. Click on Try it Out. This displays the following screen:

trigger payment execution

  1. Enter values for parameters as follows:

    • accountId - The account to be charged (example - a21f1ca3-53ec-456b-8039-7170350c9c12)

    • body - The body of the POST request. For example, to trigger a purchase transaction, you may enter the following:

{
  "transactionType": "PURCHASE",
  "amount": 10,
  "currency": "GBP"
}

  • paymentMethodId - Optional, can be left blank. If left blank, the user’s default payment method gets charged

  • X-Killbill-CreatedBy - The person/API that creates this request. You can enter any value (example - swagger-demo)

  • X-Killbill-Reason - The reason for creating the request. Optional, can be left blank.

  • X-Killbill-Comment - Additional comment. Optional, can be left blank.

trigger payment execution2

  1. Click Execute. This displays the following screen:

trigger payment execution output

So, you can see that a purchase payment is triggered against the default payment method for the specified accountId.