At the beginning of this year, PagBank – one of Brazil’s most influential online and offline payments companies – was facing problems with its documentation’s clarity, standardization, and endpoints.
We constantly advocate that investing in building excellent software documentation profoundly impacts any company. With PagBank, we leveraged their API Reference to the next level, influencing product adoption, authority, and critical KPIs.
The documentation that took part in this case study concerns the work done on the API Reference. PagBank also has User Guides, which will be covered in an upcoming project.
This article explains their challenges, how they found Write Choice, why they chose our services and method, and the astonishing results this collaboration produced in less than two months.
PagBank is a pioneer and leader in the online payments industry in Brazil. As a part of UOL, a leading Brazilian internet company, PagBank’s purpose is to democratize the financial services on the Brazilian territory and promote innovative solutions for over 29,5 million clients.
Formerly known as PagSeguro, PagBank started its operations in 2006 and provides complete online and offline payment solutions with a wide range of payment methods. PagBank’s portfolio includes payment solutions for e-commerce, serving online stores as well as commercial establishments.
In 2018, PagBank launched its IPO on the NYSE, and around 2022, it was considered the second-largest digital bank in terms of the number of clients in Brazil. PagBank has around 7,000 employees continuously delivering innovation in the Brazilian payments market. PagBank is currently expanding the financial services it provides and starting to expand its services around the globe.
PagBank approached us after receiving many complaints about their API Reference. They already had a documentation portal called PagBank Developers. However, despite the information available, customers were unsatisfied, overloading PagBank’s support team with integration-related tickets.
The support team receives requests that can be categorized into three primary issues, all of which contribute to customer frustration.
The root cause of the standardization issue can be traced back to the absence of a concrete style guide during the documentation creation process. As a result, different people used different approaches to writing and presenting visual content. As a result, users perceived a lack of uniformity, causing confusion when seeking essential information for system integration.
Moreover, the documentation writers were biased and assumed that the users knew essential concepts and information. That made the writers neglect many details, blocking customers during the integration process.
Customers trying to perform the integration also faced problems with the endpoints available on Readme. Readme allows documentation users to test API endpoints directly through the browser. However, on the PagBank documentation, the descriptions of endpoints and their parameters were poor and, in some cases, outdated. As a result, users were almost always unable to test the endpoints. They frequently did not understand the mistakes they made.
As you can see, even though PagBank is a big company that can afford an internal team to produce the documentation, they needed help finding a better way to deliver it to their users. That made them look for an experienced professional or team to work on their portal.
First, they wanted someone as an outsider to think differently and bias-free. They also didn’t want to hire in-house and go through all the bureaucracy and processes you need to approve a new vacancy, recruit, engage, and train a new professional. Also, they chose to outsource because it was the safest way to hire during the unstable economic scenario that technology companies are going through after the pandemic, so this contract would not interfere with layoff risks.
PagBank found us through referrals and scheduled a meeting to talk about their challenges. At the first moment, they told us they wanted to revamp the API Reference first and improve their portal. It is worth pointing out that they also had user guides that needed improvement, but the project started by the API Documentation.
So, on the following topics, you will see our work proposal, how we rolled out the solution, and the astounding results that came from it.
We provided the PagBank team with a suggested timeline and scope for the project. After debating and approving it, the deal was closed, and we started working on the project.
At first, we estimated about two months of work, which can be considered a long project. We split it into five sprints and grouped the tasks based on their complexity and how the documentation content relates. The sprints’ length was around seven to ten days. We allocated our best team on this project, which had a specific payment background and API Reference expertise
For the collaboration with PagBank’s team to happen, we connected with them through a Slack group. There, we could provide a seamless way to post threads and questions instead of scheduling many meetings.
We created a new Slack thread for each new service we would start documenting. First, we tried to understand every information available and listed all our questions based on that. The project owner provided the answers we needed in the same conversation.
So, for each new service, we would start a thread conversation to collect all the doubts and their answers and cover the identified gaps. This communication method is already part of Write Choice’s culture because we bring efficiency and transparency to our team and clients. Centralized threads were also used to provide weekly reports, summarizing progress, and list pending tasks and problems who resulted in delays. This routine made the progress transparent for all the team members and easy for PagBank team help in the development.
We started the project covering the primary services first. This approach helped us to get a deep understanding of PagBanks main solutions. Then, we created the user journeys for users depending on the PagBank services they were interested in. In this section, we will tell how we solved the main challenges PagBank faced within their API Reference.
A different person was responsible for documenting a service, but nobody followed a basic pattern to maintain the document’s unity. So, every time someone documented a new service, they also created a new structure. The lack of pattern made the users feel that documentation didn’t connect, which was true and made them confused.
PagBank’s former documentation didn’t have a standard for callouts, tables, or space for error pages and other important information. Before starting, we defined a style guide to be used when updating the documentation, covering the description of endpoints, parameters, and errors.
We standardized the introductions, how the users would approach each guide, and the user journeys for each available service. We created a standard to follow so the users could move from one product to the other and not have an experience breach. The standardization creates an easy to follow flow, making it easier for users to find information.
It is typical for a team that is used to the solution to neglect details while documenting the product. It happens because some writers often get biased and assume the users already know the basics.
When we started working on the documentation, we found it hard to understand several points due to missing information. We worked with the project owners to understand these topics and their gaps to ensure we covered them in the new documentation to make it clear and understandable.
At first, we tested the endpoints and realized they didn’t work. There were many problems related to their descriptions and how the documentation provided and described their parameters. Some endpoints locked the console, blocking users from testing them on Readme. Working together with the Pagbank team, we start testing endpoints following a Postman collection. Thus, we were able to identify problems and update endpoints on Readme.
We also noticed that many endpoints were duplicated in the documentation. It was due to a misunderstanding of how to present different use cases. Instead of providing use cases, they created a lot of duplicated endpoints for each situation. This isn’t the best approach since documentation users may be misled into understanding that each case has different endpoints. In addition, hiding parameters may also confuse users.
To solve the use cases problem, we created examples for each use case. Thus, users can find examples that are right together with the endpoint. In addition, for services that required deep descriptions, we created special use case pages to cover the details. One example was related to the Order API, which creates and manages the payments. Due to the high variability in the payment process associated with the selected payment method, we added specific pages where users could find all the required steps.
To wrap up, after finishing the documentation of each product, we required a review from the PagBank team. This step was essential to ensure that everything we wrote and created was aligned with their product to avoid any mistakes.
Also, the way we organized the project in sprints, the collaboration with the team, and the easy communication flow we established helped deliver the entire project two weeks earlier than expected. We estimated two months to finish it, but it took only six weeks.
We started working with PagBank at the end of May 2023, so we had access to the Readme analytics report for June. They had 40,000 views per week, which is a significant number, but they only had about 130 API calls per week and a very high error rate. As mentioned before, we addressed this when we realized that the users could not test the APIs. The way that PagBank presented the endpoints locked the console and blocked the users’ test.
Two months later, the number of views remained almost the same, but the average page quality according to Readme went from 31 to 80. Regarding the number of API calls, they grew up to ten times higher than the initial value, indicating that the users could finally test it properly.
Their homologation NPS increased from 35 to 50 after we finished the project. Also, the homologation time for each client decreased from 6 to 5 days due to the better instructions available on the documentation. The percentage of integrations with open support tickets decreased from 30% to 20%.
The CSAT metric, one of the critical KPIs in which excellent software documentation takes part, is measured monthly by PagBank. Regarding satisfaction with the documentation, PagBank asks their clients if the documentation is clear and objective. In their first result of the year, in January, only 8% of the homologated clients answered, and 29% rated the documentation positively.
We conducted the project around June, so after we delivered the new portal, they continued applying the CSAT survey. In August, they had 186 new homologated clients, and about 17% answered the question. 81% of the answers were positive about the documentation.
We attribute the success of the recent documentation revamp, as evidenced by a notable increase in user engagement and satisfaction compared to the results from the previous month.
The new documentation has undoubtedly improved the user experience. Now, they can test the APIs and have clear examples of how to do it. The API Reference result was so good that PagBank’s team asked us to translate it because they are expanding their product for new clients abroad.
As a continuation of the project, we have just started working on their User Guides and the maintenance of their API Reference. Software documentation keeps evolving, so we will keep on collaborating with PagBank’s documentation by adding information about new features and improvements.
For documentation to remain relevant, it must be constantly updated and upgraded to follow the best practices and technologies. Building new software documentation or improving an existing one is a never-ending process, so maintenance is the only way to keep up the excellent work.
When you outsource your technical writing team, the contract can be extended and adapted depending on your company’s moment and budget. That’s how we work here at Write Choice.
We are revolutionizing how tech companies educate customers about their products through excellent technical documentation and content created by a collaborative and highly skilled team. Get successful results like PagBank did. Schedule a meeting with one of our specialists using this link.
© 2025, WriteChoice. Todos os direitos reservados.
