June 9, 2021
5 min read

Simplifying PCI Compliance With Kong Gateway

Amit Mahbubani

Razorpay is a payments processor that's required to comply with PCI guidelines. This article will explain how we developed a custom Lua plugin to simplify PCI compliance with Kong Gateway.

PCI Compliance: A Quick Overview

The Payment Card Industry Data Security Standard (PCI-DSS) is a set of requirements to ensure that all companies that process, store or transmit card information maintain a secure environment. Every system component that processes, stores or transmits such information comes under the PCI system scope. Such companies are required to undergo annual audits where the system under scope is reviewed and certified.

Companies adhering to PCI-DSS requirements need to design secure and compliant systems that are easy to audit and develop on. A key consideration in these designs would be to limit the scope of the systems that come under PCI scope.

Leveraging Kong for the Ideal PCI Compliant Architecture

If your systems need to work with credit card information, an ideal architecture with PCI compliance in mind would be exposing a minimal number of system components to this information in its raw form. Here's an example of what that would look like with Kong:

The diagram above shows that the components exposed to card data are limited to Kong itself and a tokenization service. Microservices upstream receive a tokenized version of the card data and are hence out of PCI scope. Other upstream services that need to access raw card information, such as those that communicate with third-party payment gateway APIs, can do so by exchanging the token on the tokenizer. By accessing card data, these services are also brought under PCI scope. Let's break this down.

The Tokenization Service

This service replaces sensitive card information with a unique, randomly generated identifier called a token. The system can then pass this token onto upstream services without exposing card data. The tokenization service itself is out of the scope of this article. It's enough to think of it as an abstraction that provides two operations: tokenize and detokenize. In production environments, this service needs to be highly secure and PCI compliant itself. At Razorpay, we use Hashicorp's Vault for this purpose.

The PCI Handler Plugin

The plugin is a new custom Kong plugin that you would need to enable on API routes that accept card data. Its key functions are:

1. Payload Introspection – A request payload may not always have card data. The plugin will first introspect incoming request payloads to determine whether card data is present and if further action is required. Payload attribute details are available as plugin configuration.

2. Validation – This is the basic input validation of the card attributes in the payload.

3. Handle Tokenization – The system makes an API request to the tokenization service with card attributes. Then, it captures the token response.

Payload Transformation – The plugin transforms the request payload to replace the sensitive card attributes with the token. The new attribute is a plugin configuration.

Configuring Kong

1. Installing Kong

Install a basic version of Kong by following the guide for your system. Alternatively, you can clone our template starter repo, which is what we're doing next.

Note: this works with Docker.

This makes Kong Admin APIs available on, whereas the service APIs are accessible on Verify if everything's up and running: curl -i

2. Create the PCI Handler Plugin

You can write Kong plugins in Lua, Go or JavaScript. It's easy to create custom plugins with Kong's plugin development kit (PDK). Let's create a lightweight version of the pci-handler plugin with Lua:

The below snippet shows the general layout of a plugin that works with the access phase.

You can find the whole source code for this plugin here. You should store plugin files in a new directory under path – <path-to-project>/kong-plugins/pci-handler/…

Note: this is for demonstration purposes only, not intended for production use.

2. Enable and Attach the Plugin on Kong

The plugin can be attached to Kong by editing the kong.conf config file.

1. Add the plugin path to the lua_package_path key

2. Add the plugin name to the "plugins" list: plugins = bundled,pci-handler

3. Reload kong for changes to take effect. If you're using the kong-template starter kit, you can do this by running the following command: docker-compose exec kong kong reload

3. Set Up the Tokenization and Upstream Services

Given below are two snippets to set up sample tokenization and upstream services with NodeJs.



With the above setup, we now have these microservices running:

1. "Tokenizer" service, on port 8885

2. "upstream-example" service, on port 8881

4. Define Service and Routes, and Enable the Plugin

Define the upstream-example service on Kong:

1. Create the service

2. Define a route, attached to the service

3. Attach the plugin

5. Get This All Running

Let's hit the /payments endpoint on the upstream-example service via Kong:

You should see a response as follows.

We see in the response above that the upstream-service simply responded with the request body that it had received. In this case, the card attributes were replaced with a card_token attribute, meaning our pci-handler plugin is working as expected!

You can find all the above code for Kong, the plugin and sample services packaged into one Github repo here.

Fast, Scalable and Secure With Kong

Designing systems that work well with PCI-DSS is not trivial but is important to get right. With the rapid adoption of microservices taking place, delegating such mission-critical components to the API gateway makes a lot of sense. Kong's plugin architecture allowed us to significantly reduce our PCI scope, thereby increasing security and agility.

If you'd like a more in-depth look at some of the things you can build, check out the Plugin Development Guide in Kong's documentation and these resources:

If you have questions or comments, tweet us @RazorpayEngg!

To stay in touch, join the Kong Community.

Once you've successfully set up a custom Lua plugin, you may find these other tutorials helpful: