Postman is a popular tool that can be used for executing API methods. This document is aimed at providing a detailed walkthrough of how to set up Postman 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.

  • You have the Postman app installed.

  • You have a Postman account created as explained here.

Setting up Postman

Before we can execute an API method, we need to set up Postman to be able to use the Kill Bill API methods.

Create a workspace

First, we need to create a workspace in Postman. A workspace allows grouping related projects, API requests, etc. together. In order to create a workspace, you need to do the following:

  • Open Postman. This should display the following screen:

postman home

  • Click on Workspaces → New Workspace:

postman create new workspace

  • Enter a name for the workspace and click on Create Workspace:

postman create new workspace2

  • This creates a workspace as follows:

Postman create new workspace3

To know more about some advanced options related to workspaces, you can read this article.

Create a Collection

The next step is to create a Postman collection. A collection lets you group related requests together. In order to create a collection, you need to do the following:

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

  • Click Import button in the top right corner:

Import

  • Click Link and enter <KILL_BILL_HOME>/swagger.json.(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) Click Continue:

Import Link

  • Ensure that the Generate collection from imported APIs checkbox is checked and click Import:

Import Link2

  • Click Confirm and Close in the confirmation screen:

Import Link3

  • A collection is now created corresponding to the Kill Bill API methods. So, if you click on the Collections tab in the left and expand Kill Bill, this displays all the API methods as follows:

Kill Bill Collection

Configuring the collection

  • Click on the 3 dots next to the collection and click edit:

Edit Collection

  • Click on the Variables tab. Create the following variables with values for Initial Value and Current Value as specified below and click Save:

    • baseUrl - http://localhost:8080/ (Use appropriate value as per your Kill Bill installation)

    • username - admin

    • password - password

    • apikey - X-Killbill-ApiKey

    • apikeyvalue - bob

    • apisecret - X-Killbill-ApiSecret

    • apisecretvalue - lazar

variables

This defines collection variables which can then be used from requests as required.

  • Click on the Authorization tab. In the Type drop-down, select Basic Auth. Enter values for username/password as follows and click save:

    • username - {{username}}

    • password - {{password}}

authorization

This specifies that the username and password variables created earlier should be used to assign values to the username and password fields

  • Click on the Pre-request Script tab. Enter the following information:

    pm.request.headers.add({key: pm.collectionVariables.get("apikey"), value: pm.collectionVariables.get("apikeyvalue") })
 pm.request.headers.add({key: pm.collectionVariables.get("apisecret"), value: pm.collectionVariables.get("apisecretvalue") })
pre request

This sets the authentication headers using the appropriate collection variables

Using Postman

Once Postman is set up, it can be used to execute Kill Bill API methods.

Executing a GET request

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

  • Select the method to be executed from the left navigation bar. 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:

     image::https://github.com/killbill/killbill-docs/raw/v3/userguide/assets/img/postman/get_payment_methods.png[align=center]

  • Click the Authorization tab. In the Type drop-down, select Inherit Auth From Parent. Click Save:

get payment methods authorization

  • Click the Params tab. Enter appropriate values for Query Params and Path variables. In this case, only the accountId is mandatory:

get payment methods params

  • Click the Send button. This executes the request and displays the response at the bottom:

get payment methods output

Executing a POST request

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

  • Select the method to be executed from the left navigation bar. For example, to trigger a payment click on /1.0/kb/accounts/{accountId}/payments which displays the following:

trigger payment

  • Click the Authorization tab. In the Type drop-down, select Inherit Auth From Parent. Click Save:

trigger payment authorization

  • Click the Params tab. Enter appropriate values for Query Params and Path variables. In this case, only the accountId is mandatory:

trigger payment params

  • Click the Body tab. Enter the following to trigger a PURCHASE transaction:

    {
  "transactionType": "PURCHASE",
  "amount": 10,
  "currency": "GBP"
}
trigger payment body

  • Click the Send button. This executes the request and displays the response at the bottom:

trigger payment output