Adding new layers of complexity within a digital service without sacrificing user experience is a difficult endeavor. Especially for platforms that accept online payments and subscription formats, maintaining support for an increasing number of payment methods is deceptively complex.

Users don’t want to think too much about the payment process. They simply want payments to work with their preferred, custom method. However, the number of online purchase methods has soared in recent years — digital platforms must now consider support for not only credit cards or bank accounts — but Paypal, cryptocurrencies like Bitcoin, Facebook payments, Google Wallet, Apple pay, Klarna, Boku, Sofort… the list goes on.

All this is expected to behave with zero issues, but under the hood, handling diverse payment methods in an efficient way is becoming increasingly complex, requiring some serious forethought.

At the 2016 Nordic APIs Platform Summit, we were offered an exclusive sneak peak into the architecture that Spotify software engineers deploy in order to accept millions of user subscription payments each month. As they build internal APIs to handle the complexities of their payment subscriptions, their platform is an excellent case study into the power Private APIs have to streamline internal operations.

Despite architecting a custom system for their own business domain, the Spotify payment model could surely inspire other digital enterprises to introduce similar, API-driven scalable payment subscription formats into their own service framework.

The Evolution of Spotify Payments

To begin with, let’s consider how Spotify evolved. In 2006, Spotify was developed by a small team in Stockholm, and was launched to the Scandinavian market in October 2008. At that time, they only accepted credit/debit cards as a payment method.

By the end of 2011 their market increased again, spreading throughout Europe and into the United States. It was then that they added support for Paypal. In 2013 their market size increased again, and they added Boku, Sofort, Klarna, Google in-app purchases (iAP), and Facebook payments as optional payment methods.

Within this two year period their growth was impressive. As Spotify was emerging into many local markets, they decided to shift their focus from only accepting global payment methods to adding support for more local ones. To do this, in 2015 they partnered with the payment service Adyen, which allows companies to support over 250 different payment methods and 150+ currencies — truly a globalized, yet locally aware solution. They added 9 other payment methods to their stack, including bank transfer and preloaded cash cards, which increased brand engagement into areas that have seen low credit card penetration.

In 2016, they now have roughly 40 million worldwide subscribers in 60 markets. Beside delivering great musical playlists and audio experiences, their remittance goal remains consistent across the globe — to help users select the most convenient payment method.

What’s Really Going on with Online Payments?

Things like subscriptions seem like an easy process, but the workflow required for even a simple credit card payment has hidden complexity, with many working actors as well as unique edge cases to consider. First, let’s break down the workflow of a typical online payment made using a Visa credit card.

1. The user opens a line of credit with a Bank and is given a card.
2. They type their card number into a Checkout screen that ties into a Payment Backend.
3. Next, the Payment Backend will attempt to authorize the payment details with the Payment Provider.
4. If it succeeds, the Payment Provider will contact the Bank through the Credit Network to set aside money for a subscription.
5. Finally, the Bank confirms that the purchase is possible, and the response comes back to the Payment Backend through the Credit Network.

After this common flow is complete, an online subscription will be engaged. How is this communication architected? For Spotify, the process is supported by three main actors: the Client with the checkout page, the Payment Backend, and the Payment Provider. In reality, however, Spotify supports 16 different payment providers, each with unique APIs that have different implementations.

So how should a platform manage this complexity? To do it Spotify developed two smart tools: The Checkout API to help build flows that make it easy for users to enter payment details, and the Billing API to interface with the various details of Payment Providers and Credit Networks, enabling the Payment Backend to determine if they can charge a user for a subscription with a single call.

The Checkout API

The first main component is the Checkout API. To begin a subscription, the Payment Backend must try to validate payment details, and initiate the workflow mentioned above. However, in order to do this, it first needs to gather information from Spotify internally, which is in effect sourced from user input on clients like mobile or desktops. Since the type of clients are manifold, Spotify uses a state machine.

Therefore, their Payment Backend dictates the operations, controlling the workflow and requesting data from the clients. The Checkout API thus facilitates the communication between the Payment Backend and the clients.

This is necessary for the fact that extra steps may exist in a check out workflow. For example, in some countries, filling in tax information may be required. The Spotify Payment Backend needs to inform clients of the existence of this step, and the clients need to respond with a nuanced form, and collect other data as well. Other special cases may involve an offer code from an email invite to join. For all these scenarios, the backend decides what data is required, and the client must be populated with the correct form.

The key API that is driving these experiences is the Checkout API, sitting in between the Spotify clients and Payment Backend. This API enables them to create customized forms in an infinite number of iterations within Spotify clients.

Simple Checkout API Flow

1. The Client initiates a purchase, which triggers the Checkout API.
2. The Checkout API asks the Payment Backend what the next step is.
3. The Payment Backend responds saying that credit card information needs to be collected.
4. The Checkout API sends this to the Client, who uses this information to display a custom form for the user to input data into.
5. The Checkout API then sends the card data to the Payment Backend.
6. Then the Payment Backend processes the payment, confirms with the Checkout API, which initiates the Client to display the confirmation page.

These steps could easily be extended for custom form scenarios. For this to work, the business logic is always resting on the backend to dictate processes and for the clients to respond with appropriate information.

There are a few benefits to architecting a payment process this way. Having the Checkout API between the backend and client means that you can alter the checkout experience quite easily. Clients themselves can also now create native experiences, meaning that data can be moderated throughout a device to alter other apps or device-specific functions.

The Billing API

After the Payment Backend receives payment information, it needs to communicate with the Payment Providers to charge the user. Spotify’s Billing API is the bridge between the Payment Providers and their Payment Backend; the second interior API necessary for this payment flow to occur.

Since Payment Providers have different business logic (a credit charge is instant, whereas a bank transfer may take 3–5 days, for example), the Billing API is very useful. It translates these different implementations into usable data, hiding the complexity of 16 different Payment Providers from the Payment Backend, consolidating things into a single call.

The Billing API is also responsible for handling financial data, settlement, monitoring, and other duties. This allows the team to compare different payment methods, such as seeing the usage differences between Paypal and a method where SMS confirmation is required.

Sample Use Case: Automatic Alerts

A main facet of the DevOps approach is having automated alerts to allow for faster response times to system issues. Spotify leverages the internal Billing API to provide rich platform monitoring features, that are then repurposed throughout the enterprise in what they call their “anomaly detection system”. The Billing API is able to turn actions from the Payment Providers into consistent strings of events, which can then be monitored and filtered.

The varying actions for all remittance methods are boiled down into JSON exchanges with fields such as message, amount, provider, failure_code, and more. Producing standardized events for all types of payment methods enables alerting which can inform development and operations.

Keeping track of received payment transactions, and modeling this with past transaction histories, means that the system can detect trends in payment flaws. So, when a developer deploys a change that breaks the production environment, the team receives an alert. Using this same data to populate visualizations, the team can also detect if a certain payment provider is having an issue, as the data allows them to isolate individual provider activities.

Having a monitoring system for a billing API allows a company to follow trends, and become aware of local events, like bank holidays. It also can help automate internal accounting; Spotify’s approach is so fine-grained that if a small payment provider misses a due date/time for sending batch requests, the Spotify alert system will immediately notify the team.

Repurposed from Jurcut/Spotify session slides.

4 Reasons Why API Design is Critical to Subscription Services

Of all the approaches to handling payments, why should subscription services design their own internal APIs? There are a few benefits:

• APIs are platform independent: First, web APIs are designed to be used by any client. This helps hide complexity when dealing with a large number of clients and payment providers. Since the purchase method landscape is still evolving, adaptable interfaces are very important.
• Internal integrations: Other benefits include integrating with accounting platforms, payment security, or user activity monitoring. Having well-defined APIs for subscription services enables powerful data integration capabilities with other internal systems.
• Scale for growth: As a business grows, the need to build more complex products will become a concern. Therefore, having good API design helps prepare for compatibility with new business logic that will affect the company.
• Customization potential: There are many payment providers, aggregation services, or payment gateways within the market, but building your own APIs is a way to ensure customization and efficiency.

Horia Jurcut, Software Engineer at Spotify, also describes his personal affection for APIs and the positive reverberations they create within a modern business:

– APIs make it easier for multiple teams to collaborate
– APIs help you take a hard problem and divide it into more manageable domains
– APIs require documentation
– APIs enable you to rapidly test, experiment and learn.

Analysis: Scalable API-Driven Infrastructure will Power the Future of Online Payments

Spotify has impressively balanced the small and large with their payment architecture. They have successfully arbitrated complexity that has arisen out of a need to serve customization options to their users, and in doing so, have created a scalable architecture for accepting multiple payments that could be modeled at other companies.

By building consistent constructs that interface with malleable components (payment providers and clients) through APIs, they are able to both scale for global use while integrating with small payment providers, allowing their brand to cater to very local, niche audiences in specific markets.

On the user side, adding support for local payment methods is one way Spotify has honored a pledge for great consumer experiences. As the Spotify music service excels at offering custom, curated musical playlists based on user behavior, it makes sense that their payment models would allow for custom methods as well. Platform-wide consistency with an end goal to improve UX should, similarly, be the end goal at other companies. It seems that a significant portion of Spotify’s rapid, global growth is due, in part, to a well-architected payment backend.

The Spotify payment strategy is conformable within other businesses, and can act as a great architectural model for new end-user facing digital services that intend to expand to specialized markets with local payment options. Since the number of payment providers continues to climb, digital companies will very soon need to plan for how they can most efficiently accept and monitor new payment types within their subscriptions.

As the decisions made now regarding online payments will be crucial for digital platform longevity, consider how your business could parcel settlement functionality more efficiently. Whether or not you need a custom built solution is up to you. Exciting emerging financial technology APIs like Adyen, Klarna, Plaid, Stripe, Transpay, or other FinTechs will likely aid SMBs, unlocking differing payment methods so they may become globally recognized and supported services.

Though fine-grained payment options may not currently be necessary for all digital services, their ubiquity is on the rise. At the very least, from this case study we can see the benefits of creating distributed internal microservices: abstracting functionalities is key to scalability.