Payment API Experience Design

Crafting the Developer Experience (DX)

The Hidden World of E-Commerce Payments

You know when you splurge on things you really want but don't actually need? You check out and select MasterCard or Visa, and pay up. Damage done, too late .

What goes on behind the scenes are payment APIs that enable these e-commerce sites (merchants) to provide customers with different payment methods.

They come from individual payment providers such as MasterCard or Visa, or aggregators who allow you to tap into multiple payment methods through one single API such as Stripe.

For this project, I was tasked to design a developer's (user) experience with payment APIs.

Developer Sound Bites

My development experience is limited to my own website, so I would never call myself a developer. To better understand how developers think, perceive and consume information, I conducted both desk and developer (user) research.

I started with the one API I’ve ever used, Google Maps, and read through their documentation. How did they make it so easy for a non-developer like myself to understand and use? How are APIs structured and what is the order of information consumed?

Modeling after the "Hierarchy of Needs" by the famous psychologist Abraham Maslow, I discovered this framework that analyzes the different levels of developer needs for an API. It breaks down their needs from the usability and functional aspects to the creative uses of an API.

This hierarchy of values helped structure my discussion guide for the developer (user) research. I interviewed several seasoned developer friends and colleagues, specifically with experience integrating payment APIs on e-commerce sites.

Couple insights surfaced, which helped form my design principles:

Easy to integrate

An easy to follow, easy to integrate and self-explanatory API. Developers want to know what to expect - required inputs, the format and expected outcome.

Examples, examples, example

Developers often look for for example use cases that highlight not just the happy paths, but also the unhappy paths. And when they do stumble upon the unhappy paths, what are the possible error scenarios and how do they troubleshoot them?


Developers will reach out when they need help, typically through the API provider's support or StackOverflow, one of the largest forum-based developer online community.

Almost all the developers referred to Stripe as the golden standard for great API experiences.

"Stripe is like the 'Mercedes' of payments API."
— from Developer (User) Research

To the founders, Stripe wasn't just an API.

Stripe designed all the qualities developers looked for - the ease of use, the principle of putting 'Developers First' and a sense of community.

Well beyond a good support center, Stripe also engages with the developer community in sponsoring hackathons and facilitating related meetups.

Learning about Stripe's story helped me rethink the DX and pinpoint the focus area.

How might we design an intuitive and easy to follow API to support developers with the integration of payments?

Information Architecture

The face of a good API is good documentation. A good and common way to structure API content is something like this:

A standard API Information Architecture

Leading payment documentations such as Stripe and PayPal also follow a similar structure - onboarding, setup, examples, error scenarios, support and resources.

In the case of a payment API, this is what I arrived at:

Payment API information architecture

Starting from the top, the API would first cover what to expect, how to set up and some core concepts specific to the API.

The documentation goes on to highlight example use cases and suggested design guidelines. Finally, there will be a support section covering error scenarios and support options such as FAQ and feedback submission.

Developer Experience/Interface (DX/DI)

Developers experience APIs through a portal, which contains the documentation structured from the Information Architecture.

When developers integrate with a payment option, they would be interested in any design guidelines on the payment UI and front-end.

Button sizes and variations

Responsive button sizes for optimal user experience

Payment components

Recalling the design principle “easy to integrate”, great APIs typically would make their components ‘copy-and-pastable' like PayPal's. (Please note that the below scripts and copy are placeholder text for portfolio purposes.)

Depending on the merchant site's UI, they may opt for button containers.

Copy and pastable code for button containers

Alternatively, they may use radio buttons.

Copy and pastable code for radio buttons

Payment UX

Payments are multi-device experiences. Including best practices will help guide developers when designing for desktop, mobile web and mobile app contexts.

In some mobile app payment experiences, the customer will need to be redirected to another app. As users are being redirected, it will be helpful to let them know that and their expected next steps.

Setting user expectations on expected next steps

Closing Thoughts

My biggest learning was contributing to a larger design system and adapting it to a component library for API consumption. Through close collaboration with both the design and dev teams, we were able to establish that single source of truth for all products.

As I was whiteboarding these solutions, one question that came to mind was around the future of API DX.

As a developer, their current experience involves flipping through different screens, devices and operating systems to build and test APIs. Can the future of API consumption be made more convenient through voice commands instead? How can we promote inclusive design in the world of development?

Check out more portfolio stories: