Building Next-Generation APIs for Payment Solutions: A Cashfree Payments Story

Business applications and softwares have come a long way since the early and late 2000s.

In fact, they’re in stark contrast to the outdated clunky and incoherent tools.

Interestingly, we have witnessed the emergence of B2B API-first companies during this time. 

We, at Cashfree Payments, consider ourselves to be a part of that bunch. 

In this blog, we will detail how our APIs evolved with our customer needs AND just what went into creating them.

Building Next-Generation APIs for Payment Solutions: API payment Gateway
Click the image to check out our new API integration

Why We Needed To Redesign Our APIs

In 2015, Cashfree Payments emerged by making bulk payouts extremely simple for dozens of consumer applications. 

Related Read: An Exhaustive Guide On Bulk Payment

Over the next five years, we added new products and many more features. 

In the end, those initial few thousand lines of code turned into several hundred thousand lines. 

The catalyst for the same was the rapid evolution of the payment landscape and our customers’ expectations. 

We realized that we were facing major roadblocks. For instance:

  • Our APIs had become rigid and intractable for different use cases. 
  • We did not have any standard API practice across various products. 
  • We needed to create an API for UPI integration that was scaleable. The payment flow for UPI is unlike any other instrument. 

And most importantly, this:

With rapid progress, our API specifications started turning into spaghetti code and thus making them hard to maintain. 

We knew that we needed to find a solution as soon as possible. The first step was figuring out our starting point.

Starting Small: Focusing On Payment Gateway APIs

In retrospect, we realise that our APIs evolved with our company. 

In the earlier days, we decided that it was convenient to add a parameter to an existing API rather than asking users to restructure their integrations. 

However, in late 2020, we realized that we had to fundamentally change our approach and build something simpler and easier to use. 

Naturally, we could not undertake the redesign of all our APIs. So we chose to focus on the payment gateway APIs. 

But before we could move forward, we had two major factors to consider.

Setting Standards For API Design

The first factor we needed to consider while designing our API was Standardization.

At Cashfree Payments, all products are owned by independent teams. 

So, every team is responsible for their API and its vertical integration with other services. This means that we did not have a standard API design practice at Cashfree Payments. 

Building Next-Generation APIs for Payment Solutions

Now, while we wanted to set some API standards, we did not want other teams to be restricted to our opinions.

Setting an org-wide standard is always hard. Moreover, in our case, it took a lot of social capital to get alignment from everyone. 

After a lot of brainstorming, we were able to release a minimalistic set of API standards. 

Armed with these minimal API standards, we started working on the payment gateway APIs

Given the evolution of the payment industry, we needed to build APIs that worked well for every use case. 

Landscape Change In Payment Instruments in India

Now, here’s another factor that deeply affected our design choices. 

The payment landscape in India had changed completely after the growth of UPI. 

Like we mentioned before, UPI has a completely different payment flow than cards or net banking. 

At first, we aimed at moulding the API built for cards to support UPI. Resultantly, we were constrained and resorted to clever hacks. 

This was not a scalable approach and we wanted to fix it. 

So we started this exercise with two engineers and one product manager. Our only objective was to make API integrations simple and easier.

Over the next two months, we continuously iterated over the design choices for the new APIs. We looked at the standardizations built by companies like Stripe and Twilio among others. 

Building Next-Generation APIs for Payment Solutions
A sneak peak into our early discussions

Cashfree serves thousands of merchants across industries. With a plethora of payment instruments and choices, we were biased towards making API choices which makes the standard integration painless for the merchant. 

Speaking of which…

Why We Chose To Create Opinionated APIs

In the case of an opinionated API, the API creator makes some choices that are in her opinion the best. Needless to say, these choices affect the user of those APIs aka the developer. 

Now, the payment landscape in India is fairly complex. 

  • We have various payment instruments (cards, UPI, net banking, wallets and pay later) 
  • The boundary between offline and online payments has been slowly disappearing

This heterogeneity makes it hard to build a standard API for all use cases without compromising on some edge cases

We deliberated on building a large set of flexible APIs for all use cases.

But in the end, we choose to build opinionated APIs as we believe our choices make payments safer for our merchants

One of these choices is reflected in the payload that we send back to the merchant’s return_url

Unlike most other gateways, we choose to make this very simple by adding only the order_id and order_token. To confirm a payment, the merchant has to query our /orders/:order_id API. 

This small choice can actually help prevent bugs and mistakes from causing any financial loss to merchants. In the older APIs, we used to send order_status and checksum in the return_url.

Now, this could have been potentially misused by an adversary leading to financial loss for the merchant. 

Evidently, as a payment aggregator, payment security is our utmost priority. 

Dogfooding Our Own APIs

We decided to use our new APIs within our javascript and mobile SDKs. 

Dogfooding our own APIs helped us understand them from the merchant’s perspective. 

Building Next-Generation APIs for Payment Solutions

It also helped us weed out small but relevant bugs.

At the end of the day, we want all our SDKs to consume the same APIs we deliver to merchants. 

This helps us keep a common denominator for all our abstractions (SDKs, etc.), making it possible to build disparate payment flows from these common APIs. 

This also helps us structure our teams and a single team can take care of all external facing APIs. We avoid building custom solutions for any specific platform, helping maintain our APIs in the long run. 

While we used our APIs extensively, the real challenge was to ensure that merchants try them out. Ensuring an effortless migration was one of our foremost design principles. 

Ensuring a Friction Free Migration

As we started working on the API design, it became easy to get caught up in pursuing pure solutions. 

However, pure solutions don’t matter much if they cannot readily be used by others.

So, we offered our merchants a choice. 

They could use the new APIs alongside the existing APIs. 

This way a merchant could move one API at a time without any hassle. As merchants did not have to do a full-blown migration, the switching cost was minimal.

Our adoption metrics for existing merchants clearly showed that most of them migrated only one specific API in the beginning. Slowly moving other APIs

Built and Iterate Fast: Shipping Products Faster

One of the challenges with any big project is the scope of the work. 

It was never possible for us to fit all use cases in the first iteration of the API. 

We consciously added limited flows in our first release, so we could ship the product faster

We also knew that some of our decisions were bound to be subjective. In those cases, we made a choice and went ahead with it. 

In fact, we could say that the words of Voltaire acted as a guiding principle for our project:  “Do not let the perfect be the enemy of the good”. 

More than just an API: The Way Forward

Just like most payment companies, our APIs are built with increasing complexity so that our merchants could have the easiest integration experience. What’s more, our tech queries have decreased significantly because of the simplicity of the new API integration.

However, our work on these APIs has just started and we still have a long way to go.

For instance one of the most critical parts of an API product is how we help users overcome errors in real-time. While we have built automated workflows to help users here, we still have a lot of ground to cover.

As the payment landscape evolves, so will our APIs. 

All in all, this exercise gave us great insight into building something radical while doing away with systems that work but don’t scale

Did our story interest you?

There are lots more to come!

In fact, you can be a part of our story while we build payment solutions for the next generation of businesses.

Building Next-Generation APIs for Payment Solutions cta