NuPay API Documentation

In 2022, Nubank launched NuPay, a cutting-edge payment solution. To ensure a seamless integration experience, we overhauled our API documentation, addressing outdated and inaccurate information.

As NuPay gained traction among major players, I was part of an ambitious project to redesign the documentation.

Due to a non-disclosure agreement (NDA), I have changed or hidden some confidential information about this project. Nevertheless, I have ensured that all essential details are included, and All opinions expressed in this portfolio are my own and do not necessarily reflect the views of Nubank.

What is NuPay?

NuPay, developed by Nubank, is a payment method integrated through our API, exclusively for Nubank customers. We offer resources, support from our implementation team, and API documentation to assist merchants in the development process, providing their customers with specific benefits.

The mapping to identify all the documents. Actual cards were hidden behind the grouping cards

The challange

Nubank is known for simplifying the banking segment and delivering an outstanding experience through customer experience, design, and transparency.

In under two years, NuPay expanded its services from small businesses to large corporations such as Uber and Ifood. Describing a rapidly growing product poses challenges, especially when adding new features without a streamlined update process.

As a result, the documentation API for merchants became disorganized, with outdated and scattered information on different platforms. This left merchants heavily dependent on the integration team for ongoing support.

My role and the team

Together with Gabriela Neri and Fernando Junior, we conducted both the discovery and implementation processes.

You can refer to the documentation published on August 30th, and stay tuned for future updates and improvements.

Our goals 🎯

To deliver the same experience to our B2B clients.
To build a scalable structure so other teams can create new features with confidence
Provide a better integration experience for the merchant’s team.

1. Kick off

At the outset, we faced uncertainty regarding what would enhance the integration experience. Merchants vary in their specific needs, and what might be an issue for one may not apply to another. Our starting point was the limited insights available from post-implementation interviews, which were conducted by me and Gabriela.

First insights 💡

After each successful implementation, we interviewed merchants to identify opportunities and pain points, collecting valuable data since May 2022.

Initial insights consistently highlighted concerns about product functionalities, documentation, and our developed tools.

These findings suggested that improving the current documentation could be a path toward our goal of enhancing the integration experience for the merchant team.

Key insights from the interviews focused on the integration experience. Any unrelated insights have been omitted.

Designers coding

To collect more insights from the hypothesis of working on our current documentation we decided that we should try integrating following the current guides. Thinking as a non-focal group test exercise we thought that if the documentation was clear enough, designers like us could at least do the first steps. Of course, that was a complete failure and we didn't even know how to start it.

2. The Discovery

After gaining insights from the merchant's perspective, we turned our attention inward. As we mapped all the documents we had created, another hypothesis emerged: the need for so many documents may have arisen from the fact that our documentation was not functional.

Different areas, different "solutions"

Each department attempted to address the lack of essential operational information in their own way. Business and strategic teams used spreadsheets and presentations, tools they were familiar with. Designers employed Figma for creating resources, while the implementation team heavily relied on constant communication.

Deeper insights

We analyzed contact rates during the integration phase, despite the challenge of isolating influencing factors. This baseline was crucial. Through diagrams, we identified areas in the NuPay experience that generated the most questions. Our analysis revealed a consistent average of at least 5 monthly contacts seeking help with integration difficulties. We mapped each contact within the journey represented on the diagram. This data was instrumental in shaping our execution plan and establishing clear priorities.

Turnin things measurable

We needed a way to track integration progress on a weekly basis, as close contact with our implementation team alone didn't provide a clear view of the merchant's progress. We parameterized each step of the process and assigned values to them. As the merchant advanced, we updated the percentage completion.

While it's a manual process relying on our team's perception, this tool has significantly enhanced our implementation operations and has been consistently used by the team.

Implementation tracker created by us.

Documentation Analysis

Upon attempting to integrate NuPay using the documentation guide, we identified several issues:

Unclear navigation structure.
Mixing of different products within the same page/section, including our instant payment solution and NuPay.
Inconsistent writing.
Lack of examples, especially for edge cases.
Absence of explanations related to user experience (UX).
Outdated content
No testing and validation guide.

The documentation before. No clear vertical organization and the content mixed different product descriptions.

3. Framing the problem

The initial interaction with our API begins with our documentation. Interviews revealed that outdated information and a confusing structure were not only leading to mistakes but also causing frustration within the merchant's team, resulting in integration setbacks. Large merchants, in particular, expect a comprehensive error-free guide. Each incorrect piece of information erodes their confidence in us, potentially jeopardizing deals.

Implementation tracker created by us.

As we mapped the merchant team's journey to consolidate notes, insights, pain points, and feedback, it became evident that information played a crucial role throughout the integration process. The current integration experience suffered from significant friction due to a lack of information.
This raised the question:

“How might we simplify the content to make the merchant team feel confident and excited about implementing Nupay?”

Decision-Making Process

Our research provided us with the confidence to make informed decisions, considering the following factors:

Capacity

Our development team was already occupied with other tasks, making it impractical to rely on them for page development.
Given my limited Git and development experience from past courses, we opted to take responsibility for the prototype and development, involving Gabriela and Fernando.
This approach placed the challenge firmly within our control and responsibility, with most of the work depending on us.

Technology:

We utilized Dosify, an open-source documentation generator using Markdown files to create static websites.
The short learning curve for Markdown made it accessible even to those without prior experience.
Having Gabriela with a developer background provided valuable validation.

Research-based

The merchant development team's frustration with the current documentation was a clear indicator.
Issues such as the lack of information, examples, and handling of edge cases were causing delays in NuPay implementation.
Outdated API examples in the documentation added to the challenges.
Despite creating various documents, sheets, and Figma resources to address these issues, merchants were overwhelmed by the multitude of materials.

Infrastructure

The existing structure was live, with alpha, beta, and production versions in place.
Git management allowed simultaneous work and version control

The CSD (Certainties, Suppositions, Doubts) matrix proved to be a vital tool in achieving decision clarity

4. Solution

Now that our goals were clear, we began discussions on the desired structure and content for the new documentation.

While we didn't aim to create an entire developer portal like Stripe's, there was a significant amount of content to be included. We needed a plan to determine where to begin.

Milestones

Our strategy was organized to allow the alpha version of the document to be released and shared with merchants for validation and feedback collection.

Milestone 1: Alpha Release - Overview & Setup Content

Focus: Introduction, starting steps, and integration overview.
Included a team iteration to collect feedback and implement quick fixes and improvements.

Milestone 2: Alpha Release - APIs Content - Payment with NuPay in the app

Focus: Core explanation of our first product, NuPay, which completes payments within the Nubank app.

Milestone 3: Integration Milestones

Milestone 3.1: NuPay saved in the checkout - App to App
Milestone 3.2: NuPay saved in the checkout CIBA - Browser Authentication
Milestone 3.3: Payment Conditions
Focus: Enabling merchant checkouts for automatic NuPay payments and providing payment method consultation for customers.

Milestone 4: Pix

Focus: Instant payment solution.

Milestone 5: English Version Publication

Focus: Translating all previous content and publishing the English version.
Included content for in-app setup, UX, APIs, tests, and validation.

This planning allowed us to track our progress effectively. While it took us one month to deliver Milestone 1, we gained momentum and completed the subsequent milestones within another month.

While we didn't strictly adhere to the plan, having clear priorities made it easier to adapt to changing situations.

Mindmap, prototyping and coding.

With clear content priorities in mind, we created a mind map for a comprehensive overview, serving as a checklist to ensure all essential content was covered.

The preliminary work clarified content grouping, which informed our exploration of sidebar navigation placement.

With the new structure in place, we began designing alternatives that addressed the defined requirements:

Incorporating UX guidelines.
Adding more code examples.
Creating a step-by-step guide labeled 'Start Here.'
Including a testing guide section.

After iterating and refining the design, we divided our tasks to work more efficiently, alternating between coding and designing.

Prototyped Screens

Mindmap

5. Summary

The new API documentation was released in August 2023. We are currently monitoring feedback from merchants implementing NuPay.

Initial metrics for improvements

Reduce perceived integration/development time
Fewer rollbacks and less merchant rework
Positive feedback on post-implementation interviews
UX metrics
Quantitative and qualitative data with Google Analytics events
Option to review the content (Useful yes/no + open text for comments)

🎯What we achieved

Simplified the documentation coding architecture for easier maintenance and updates.
Established a scalable updating process, providing teams with a playbook to cover essential documentation aspects.

✍🏾What we've learned

Not all previously created documents needed to be discarded. A detailed use case spreadsheet, created earlier by me and my colleague Amanda from the implementation team, remained valuable. Merchants could generate a copy and edit it for test planning. The new documentation made the spreadsheet simpler by removing setup information and focusing its content.
Figma proved to be an effective tool for explaining user experience. We utilized Figma's iframe export feature, enabling us to avoid including every screen of the experience. Instead, we created a resources page with Figma in iframe format, allowing readers to navigate through the file without leaving the page.
The insights gained from the Design Thinking process provided the confidence needed to make informed decisions. While not everything proceeded as planned, we remained adaptable. Our ongoing efforts are focused on further enhancements to elevate our documentation to a best-in-class standard.

You can refer to the documentation published on August 30th, and stay tuned for future updates and improvements.