Analyzing the API Docs and DX Patterns in the Best FinTech Developer Portals

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 software developers and business 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.

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.

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.

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.

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.

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 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.

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.

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.

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.

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.

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.

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.

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

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.

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

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

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.

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.

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.

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.

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.

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 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.

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.

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

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.

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.

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.

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.

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.

The developer journey stages and great API documentation practices

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.

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:

• Adyen
• Braintree
• Chargify
• Cybersource
• Mastercard
• Paymentwall
• PayPal
• Shopify
• Square
• Stripe
• Veem
• Visa
• Worldpay
• Yodlee

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

Posts in this series:

• Introductory post
• Analyzing the API Docs and DX Patterns in the Best Banking Developer Portals
• Analyzing the API Docs and DX Patterns in the Best Telecommunication Developer Portals
• Analyzing the API Docs and DX Patterns in the Best Media Developer Portals
• Analyzing the API Docs and DX Patterns in the Best Media Developer Portals 2