Payment API Portal Design

Crafting the Developer Experience (DX)


Behind the scenes of E-commerce Payments

Working on a client project at HSBC bank’s headquarters in Hong Kong, I was tasked to lead the discovery and MVP designs of the developer experience (DX) for a new payment API.

At the time, HSBC already had an existing QR-based consumer payment mobile app, PayMe, with 1.5+ million users and identified an opportunity to expand their solution to businesses via a payment API offering.


UX Design Lead

I worked with HSBC's product and design teams to lead the design process from discovery research, prototyping to the development of an early stage concept for PayMe's developer API portal.

For my final deliverable, I coded the API portal on Microsoft Azure and collaborated closely with developers and technical writers to insert the relevant content and codes.

(Please note that the details showcased have been edited to maintain confidentiality.)


Developer sound bites

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. What are the possible error scenarios and how can developers 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 of 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


How might we...

Stripe isn't just an API product. It's a developer experience - the API's ease of use, the principle of'Developers First', and a sense of community.

Learning about the Stripe 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?


Structuring the Developer Experience (DX)

The face of a good API is good documentation.

Leading payment APIs such as Stripe and PayPal all follow a similar structure - from onboarding, setup, examples, error scenarios, support to resources. This is fairly in line with the developer’s expected journey.

Leveraging this mental model, this is what I arrived at:

Payment API information architecture

Starting from the top, the API would 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's journey with PayMe API

Simplified user flow (happy path) from sign up to API consumption


The API Interface

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

The API portal

Looking at some of the key components, developers look for 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.

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


A new payment option for consumers

With a fully functioning MVP, HSBC was able to quickly launch this payment API into beta and acquire target ecommerce businesses. The success metrics will be based on the number of ecommerce businesses acquired and ultimately the adoption rates of consumers paying with PayMe.

Once businesses add PayMe as a new payment method, it will bring convenience to the 1.5+ million customers using PayMe.


API implications

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 evolve the design system and establish a single source of truth for both merchant (B2B) and customer (B2C) experiences.

As I was whiteboarding these solutions, I started to wonder about the future of API experiences.

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 might we promote inclusive design in the world of development?

Check out more portfolio stories: