The financing industry offers so many good examples of developer portals that after focusing on traditional banking APIs in the first part of our series, we felt the need to continue with various portals from the FinTech area. As opposed to banks, most companies in this group were born into the digital / API world. There are numerous great portals in this field which makes it a real challenge to select only a few. We looked into several portals and in this post we included those that have some of the best and most innovative practices based on our research.

We will focus on two main areas:
(1) the available information resources,
(2) API docs quality criteria.

You can read more about the background to these two concepts and why we chose them in our introductory post.

We modeled the steps taken by a developer persona looking for an API implementation from start to finish, and we follow this downstream developer journey to give our idea on what we think to be the FinTech industry's current most innovative and remarkable solutions in architecting and presenting information on a developer portal.

Discover and research

How can this portal help me solve my specific task?

The landing page of a developer portal can focus on various audiences or documentation components. For example: Braintree aims at serving the needs of both developers and decision makers. Their Access Control Panel directs developers to Sandbox or Production, while the Articles for business users section contains more general information on the basics of payments and security.

The Access Control Panel allows users to choose between sandbox and production while the Articles for business users are for decision makers



PayPal and Stripe have several APIs, and their approach on the landing page is to offer an overview of the services these APIs can be used for. Besides focusing on developers with the Try now section right below the catalog, Stripe doesn’t forget about non-developers either. It offers links to plugins for third-party software and to Stripe integrations from others.

Third-party integrations for non-developers



Mastercard offers a carousel on its landing page with three different sections, all of them providing CTAs for users with specific needs: Blog, Use cases, or the API catalog.

In our understanding a developer portal contains the API documentation, as well as it is a self-service support hub, a trust signal, a communication nexus for API stakeholders and a key DevRel tool: all this is what helps an organization to provide the best possible developer experience for its APIs.

Square’s developer APIs landing page reiterates that there is not yet a standard terminology in the world of developer portals: their Developer Portal is only for setting up a developer account and start working with the API. Everything else, such as Get Started, Testing, Release Notes, Reference, etc. is under Documentation.

Square's landing page



The landing page of Visa looks different from the other portals we checked in this part of our article series, in the sense that besides providing an API catalog, the main focus is on Use Cases and Partner Showcases. The Use Cases describe scenarios in which specific APIs can be used. The Partner Showcases present real life application examples from Visa partners.

Visa provides examples through Use cases and Partner showcases



However, if you scroll down on the landing page it is clear that Visa addresses different groups of users. There are different sections with different CTA buttons: a section about the Visa developer program with CTAs either for more information or immediate registration, an engagement section where you have access either to Developer Tools, the Blog or the Community, and there is also a CTA to access sample codes on GitHub.

Paymentwall has a clear developer focus. Their landing page is basically the Getting started guide with all the necessary steps. What is more, they also provide an Integration checklist to follow.

Paymentwall makes the integration process easier with an Integration Checklist



Evaluate

Can I trust this organization’s commitment to its APIs?

During the second, "evaluation" stage of their journey users try to decide whether the portal and its APIs are suitable for reaching their goals.

Visa provides a very clear overview of its products and their availability. First, the Docs are categorized into Global Docs, Standards & Guides, and API Docs. The API Docs are further classified into fields for which the APIs are intended, such as Commercial, Payment Methods, Data and Analytics, Risk and Fraud, Trials, Offers and Benefits.

The Docs on Visa’s portal are categorized into three groups



The landing pages of the specific APIs are also well-structured and the important information, such as limitations, regional availability and key features, is readily available.

Detailed information on the API readily available on Visa’s page



For task-driven, code-oriented developers testing can be the best option to make sure that they have found the API solution they were looking for. As data security is central in FinTech, sandbox is usually the first choice for testing as it provides mock data so developers can see the actual working of the API without having to compromise data security. The sandbox testing option is used by almost all of the portals we analyzed in this article. Postman is another popular choice for testing purposes, for example Square offers a Run in Postman button in their reference. Versioning information and release notes can help a lot in building trust towards the organization and its APIs. A best practice we can see on many portals is to provide information on versioning in a clearly visible, yet not central place.

Information on versioning on a clearly visible place on Adyen’s, Visa’s and Veem’s portal



Get started

Where do I begin?

Braintree’s Getting started section looks exemplary in helping developers find what they need while at the same time giving an introduction to their products. On one hand, they offer SDKs in several languages.

SDKs available in different languages by Braintree



On the other hand, the visual diagram that explains the working of the APIs is in itself very helpful, but its efficiency is further improved by short explanations under the image with links pointing to the relevant sections of the documentation.

Visual on the working of the API by Braintree



Adyen also created a Get started section that strives to make the whole process easily understandable for users. It is a combination of a visual and a sidebar menu. Clicking an item of the sidebar menu reveals the relevant part of the visual and a short explanation of the step.

Get started visual by Adyen



The jargon used in the financial sector might often be challenging for users, so a lot of portals provide a glossary with the most relevant financial terms, but also with expressions specific to the world of APIs.

Paypal has a glossary on API related terminology, Adyen has one on payment terms, Chargify explains the notion of dunning in a video tutorial, while Shopify applies a cool DX solution: expressions that might require an explanation are underlined with a dotted line and hovering over them reveals their definition.

Pop-up definition of key terms by Shopify



Implement and troubleshoot

Do I know everything to make this work?

In the troubleshoot and implementation sections we’ve noticed a lot of parallels with the solutions that banking developer portals use (see the first part of our series). Adyen built their own API explorer based on Open API. The API explorer appears as a collapsible third column and it has great features like a copy button in the bottom, and users can also choose from the available SDKs for iOS, Android, and Web in a drop down menu on the top.

Adyen’s own API explorer



Square also has three-column reference docs, with a language selector and a button that allows users to test their code in Postman.

Reference by Square with a Run in Postman button



Instead of a collapsible third-column Visa uses a Code Explorer with the same function. The portals we checked pay particular attention to assist the implementation process as much as possible. Yodlee and Cybersource created a Best practices section to recommend tried-out solutions.

Best practices offered by Yodlee



Paymentwall has a checklist with the regulatory e-commerce website standards required to use its services.

Website requirement for future users of Paymentwall



Square provides a detailed explanation on data handling, showing that it cares about the products built with its APIs.

Best practices about collecting information from Square



A lot of FinTech companies help in the design of the application or payment site using their APIs. Worldpay has a Payment Page Designer with a detailed tutorial and video guide. PayPal has a Button Manager API and Veem provides downloadable Button images.

Button images by Veem



FAQ pages and direct contact sections done well can help in reducing developers’ frustration.
Braintree has an especially detailed Contact form. As a first step you can choose the type of your problem, and you will immediately be directed to the proper documentation. If this doesn’t help, the next step is to give a detailed description of your issue and upload screenshots or code snippets, to get troubleshoot support.

Detailed Contact us form of Braintree



Research shows that many developers tend to turn to third-party resources when looking for help. Adyen embraces the “go where the developers go” maxim: it gives its users a link to turn to StackOverflow or ask for direct support with problems during implementation.

Quick access to Stack Overflow on Adyen’s portal



PayPal offers several possibilities to ask for support. If checking the FAQ section doesn’t help, you can turn to the Technical Support Community with your questions or Report a Bug or Integration Issue.

Celebrate

Will they care about my work?

Doing user research is indispensable to create great Developer eXperience and data collection via feedback can be an important step in this process. Besides, asking for feedback is a great way to engage users to make your docs better. Braintree asks their devs how helpful they find a given page or section. Interestingly, they exercise two different methods for this: in the end of the Getting started sections users are forwarded to a Google form if they want to rate, while the Tutorial section ends with a simple question and users can give a thumb up or down.

Google form for feedback on Braintree’s portal



Braintree asks for rating in the end of every section



PayPal also has a Google form at the end of every section to ask for feedback. The first question of the form asks whether you are giving feedback on the documentation or the product. This basic question can ensure the data you get from the feedbacks are relevant to the field you would like to research. Adyen uses a floating feedback section in the documentation, which appears when a user has spent a specific amount of time at the given section.

Floating feedback section on Adyen’s portal



Shopify asks visitors to rate their docs on a one to five scale and follows up with a question. Asking for the users’ opinion on how a page can be improved is quite common, but Shopify also asks what users like about the page if they hit the best rating.

Shopify would also like to know why users find their portal great



Shopify has previously been mentioned as a good example on how to create a developer community. On their community page users can discuss any topic in relation with the portal or the products.

Shopify directs users towards their community pages



In our previous post we mentioned two reasons why creating a community can be beneficial for the company. First, it reflects the appreciation towards the users and second, it is a great opportunity for viral marketing.
While it is true that not every company needs a community forum, as these can easily become tumbleweed towns without a community manager, Shopify’s community forum is an example on how it can be done well. Besides the forum, Shopify also has a Blog, Events, Unite (conferences), and a Twitter section too.

Various sections of Shopify’s community page



Visa also has a great community page, with Forum, Blog, Developer Tools and Webinars section, all of which can be browsed by category.

Visa’s developer community



Maintain

How hard will it be to keep this running?

Effective communication about the changes of the API is essential in convincing users that they won’t have serious issues running their implementations. Stripe offers two options to get information about the changes of its APIs: there is a forum, called API Discussion Board and users can also sign up for the Developer Digest, which sends updates about the APIs.

Possibility to sign up for information on updates on Stripe’s portal



A lot of portals have a separate Release notes section, for example Square, Visa, Cybersource.
Shopify have a detailed changelog available from the main menu of its landing page: the most recent updates are highlighted,the rest can be filtered by tags, and this company also has a Twitter account and an e-mail notification system that it uses to inform users about changes.

Quality checklist

Among the portals that we analyzed in the FinTech sector, we also found great examples of the features that are crucial according to developers: interactivity, readability, consumability, search function, service information.

As for interactivity, all of the portals we checked provide easily accessible features for testing, which is most often a sandbox environment. The collapsible third-column in the reference documentation also became common practice. The Run in Postman button in Square’s reference docs gives access to an external testing option. Square also provides a great example on how to improve readability: they put a table of content at the beginning of the main sections.

Square has a table of content at the beginning of the main sections



Stripe and Chargify enhance consumability by dynamically changing the URL for every section throughout the documentation. On Stripe’s portal the URL also changes with the selected language in the reference docs.

Stripe's URL changes dynamically at every section



Visa has a lot of APIs for various purposes, and it gives a great example on how searching for the right one can be made easier. In the API browser the catalog can be filtered by categories and target users.

Visa's API browser



Another remarkable feature on Visa’s developer portal is that information on regional availability is clearly indicated in the Availability Matrix .

Another important piece of information about the API from a business point of view is on pricing. Square gives comprehensive information on pricing in a very clear way.

Detailed information on pricing from Square



Devportal Quality Aspect Examples
Interactivity Reference docs with collapsible third-column
Code explorer
Sandbox
Run in Postman button
Readability Table of Content for each section
Plain English
Consumability Copy buttons
Dynamically changing URLs
Searchability Filters
Tags
Search bars
Information on the service Visuals on limitations and pricing
Regional access
Business models



The developer journey stages and great API documentation practices

Stage Think about
Discover Landing page
Focus on various users
Visuals on the working of the APIs
Case studies
Partner showcases
Evaluate Information on versioning
Clear overview
Availability
Changelog
Sandbox
Get started Visuals
Training videos
Glossary
Postman
Code samples and examples
SDKs
Implement and Troubleshoot Reference docs
FAQ section
Community section
Best practices
Standards
Design support
Button images
Celebrate News & Events
Blog
Feedback opportunity
Third-party resources
Maintain Changelog
Release notes

Beyond great documentation

In the first part of our series we said that even the best APIs need a well-designed developer portal, to see the adoption they deserve. This is even more so in case of the FinTech industry which is often seen as the trailblazer of the financial sector. Keeping an eye on the API and developer portal related innovations in the FinTech industry can be beneficial for other segments too. We have analyzed a variety of portals in our selection, but our list is far from being exhaustive. We would be happy to hear about your ideas in a comment below.



Free and open source API documentation tools

Don't forget that the DevPortal Awards nomination is open!

Submit your nomination



The portals we analyzed

For this part of our series we brought examples from the following developer portals:



Thank you so much Kathleen De Roo for the guidance and Laura Vass and Kristof van Tomme for the editing!


Posts in this series:

About the author

Mónika Alföldi-Zörgő

Copywriter

Mónika works as a copywriter for Pronovix. Her main tasks are doing research on developer portals and writing blog posts on the findings. After 10 years of teaching English and Italian, and four years of translating and interpreting she was looking for brand new professional challenges and found them at Pronovix. She enjoys delving more and more deeply into the field of developer portals and technology and share what she has learned.