PagBrasil’s Automatic Pix: Integration Guide for Developers

The payments landscape in Brazil has been transformed by the arrival of Pix, a system that quickly became popular due to its speed and availability. For businesses that operate through subscription models, monthly fees, or any kind of recurring billing, the natural next step is Automatic Pix. It combines the efficiency of Pix with the predictability and automation needed to manage ongoing payments.

PagBrasil, always at the forefront of payment innovation, offers a robust and flexible Automatic Pix solution designed to streamline the recurring billing experience for both businesses and their customers. This technical guide is your comprehensive resource for integrating PagBrasil’s Automatic Pix via API. Here, developers will find the essential information needed to implement a recurring payment solution that is efficient, secure, and fully tailored to their system’s.

The Power of Automatic Pix for Subscriptions and Recurring Payments

Pix, the instant payment method developed by Brazil’s Central Bank, has revolutionized financial transactions in the country by enabling transfers and payments in under 10 seconds, 24/7—including weekends and holidays. Its widespread adoption and the convenience it offers users have paved the way for innovation across multiple areas of payment.

For business models based on subscriptions, recurring services, monthly fees, or any setup that requires periodic payments, Automatic Pix emerges as the ideal evolution. It brings the speed and simplicity of Pix to the world of recurring payments, removing friction and enhancing the experience for both merchants and customers. By selecting Automatic Pix at checkout, users can scan a QR code with their smartphones to authorize future automatic recurring charges.

It’s in this context that PagBrasil’s Automatic Pix solution stands out. We understand how critical security and flexibility are for recurring operations. That’s why our platform is built on solid foundations:

• Robust security: Communication with our API is protected by HTTPS, and each transaction is validated through authentication mechanisms. In addition, PagBrasil implements safeguards against abuse or misuse of the API, including rate limiting or similar restrictive measures to ensure the system’s integrity.
• Customizable consent flows: PagBrasil offers two journey options for using Automatic Pix:
• Initial payment + consent: The user makes an initial payment while simultaneously granting authorization for future automatic recurring charges. This flow is detailed in Section 4 of the integration documentation, which you can find directly on the PagBrasil dashboard, typically under the “Resources” section.
  • Consent only: The user simply grants authorization for future charges, without the need for an immediate payment. This model is ideal for scenarios such as free trial periods for services, and its integration flow is outlined in Section 6 of the documentation found on the PagBrasil dashboard.
• Control and customization: API integration offers a level of personalization that allows developers to tailor the payment experience to the specific needs of their business.

Understanding how to integrate this powerful tool is essential for developers looking to implement or enhance recurring billing systems. PagBrasil’s API provides the necessary features to build a smooth and secure payment experience, fully leveraging the potential of Automatic Pix.

Why Integrate via API? Benefits for the Developer

Often API integration is not just one option—it’s the most effective and, in many cases, the only viable way to fully incorporate this advanced recurring payment functionality. The need for API arises, for example, when there is no “plug and play” solution directly compatible with the merchant’s specific platform or application, or when the inherent limitations of such systems call for a more granular and customized approach.

In these situations, the API is the key to unlocking the full potential of a solution, putting power and flexibility in the hands of the development team. This enables a precise alignment between the payment solution and the application’s business rules, ensuring a tailor-made implementation. Let’s take a look at the main benefits this approach offers:

Full Control Over User Experience (UX)

By integrating via API, you keep the customer within your environment throughout the entire checkout and consent process. This avoids unnecessary redirects that can lead to distrust or cart abandonment.

You have the freedom to design the payment interface, ensuring it aligns with your system’s visual identity and user experience (UX). The online store sends the order information to PagBrasil and then displays the QR code and alternative code provided by PagBrasil.

Flexibility to Customize the Checkout Flow

Adapt the payment and consent request flow to the specific needs of your product or service. For example, you can decide the exact moment to present recurring payment options or how to collect the necessary information.

The API allows you to send a wide range of parameters, such as product name, customer data (name, CPF/CNPJ, email, phone number, full address), amount, and specific details of the recurrence—like billing cycle, date of the first charge, and the subscription description displayed in the customer’s banking app.

Direct Integration with Your Business Logic

Integrate recurring payment management directly into your internal systems, such as Customer Relationship Management (CRM), Enterprise Resource Planning (ERP), or other platforms.

Automate order creation and consent requests based on events in your system, such as signing up for a new plan or renewing a subscription.

Automation of Payment and Notification Processes

Receive instant notifications (webhooks) about the status of payments and consents. This allows your system to respond in real time—granting access to products, updating subscription statuses, or communicating with the customer.

PagBrasil notifies the merchant when the payment or consent has been authorized, allowing the store to process the order and deliver the product.

Schedule future recurring charges automatically using the recurrence ID obtained at the time of consent.

By choosing PagBrasil’s Automatic Pix API integration, you’re not just adding a payment method to your system; you’re implementing a complete, adaptable solution that can streamline processes, enhance the customer experience, and boost the operational efficiency of your recurring business. It’s the ultimate solution for developers seeking robustness, control, and customization in scenarios that require direct and in-depth integration.

Understanding the Integration Flows

One of the key advantages of PagBrasil’s Automatic Pix solution is its flexibility to adapt to different business models and customer acquisition strategies. This is reflected in the two integration flows supported by the API, which allow either charging an initial amount at the time of consent or simply obtaining authorization for future charges.

Understanding these two approaches is crucial for developers to choose the most suitable flow for each specific use case, ensuring an optimized user experience that aligns with the company’s goals.

Flow 1: Initial Payment + Consent

In this model, the customer makes a Pix payment at the same time they grant authorization for future automatic recurring charges. It’s the most common flow for starting paid subscriptions, where the first billing cycle is charged at the moment of sign-up.

Technical flow (summary):

1. Your application sends a request to PagBrasil’s order creation endpoint, including order details, customer information, and specific recurrence parameters.
2. PagBrasil returns the link with the Pix QR code image and the “copy and paste” code.
3. After the customer completes the payment and gives consent, PagBrasil notifies your application about the authorization.

Ideal use case:

• Starting software subscriptions (SaaS) where the first month/period is paid at the time of sign-up.
• Subscription boxes that charge the first monthly fee before shipping the initial product.
• Services that require an initial payment for activation followed by recurring charges.

The detailed flow for this journey, including all request parameters and response details, can be found in Section 4 of the Automatic Pix integration documentation found on the PagBrasil dashboard.

Flow 2: Consent Only (Without Initial Payment)

This flow allows the customer to authorize future recurring Pix charges without needing to make an immediate payment. It’s an excellent strategy for offering free trial periods of a service, for example.

Technical flow (summary):

1. Your application sends a POST request to PagBrasil’s consent creation endpoint, including the customer data and recurrence parameters.
2. PagBrasil returns the necessary information for the customer to authorize the recurrence in their banking app.
3. After the customer gives consent, PagBrasil notifies your application about the recurrence authorization.

Ideal use case:

• Offering trial periods for online services, where the customer registers the payment method and gives consent, but the first charge only occurs after the free period ends.
• Freemium models that request advance consent in order to automatically unlock premium features in the future.
• Scenarios where billing starts at a different time than registration, such as enrollments with deferred payment initiation.

The complete details on how to implement this flow, including the specific parameters for the consent request, are provided in Section 6 of the Automatic Pix integration documentation on the PagBrasil dashboard.

The choice between these flows will depend entirely on your application’s business strategy. PagBrasil’s API is designed to provide the flexibility needed for both scenarios, ensuring you can deliver the best recurring payment integration experience with Automatic Pix.

Handling Responses: QR Code, Webhooks, and Status

After sending a request to PagBrasil’s API, your application must be prepared to handle the synchronous response and, most importantly, the asynchronous notifications (Webhooks) that report on the progress of the transaction or consent. Additionally, the API provides endpoints for on-demand status checks.

Initial API Response (Synchronous)

The immediate API response varies depending on the endpoint used:

Initial payment + consent

• The API will return a response containing the order details.
• The key elements in this response are pix_image (the URL of the Pix QR code image) and pix_code (the alternative “copy and paste” code for mobile users who can’t scan the QR code).
• Your application should display the QR code and/or the code so the customer can complete the payment and give consent through their banking app. The response format is the same as that of an API status query.

Consent only:

• The response will also include the recurrence details, using the same format as a status query via the API.
• In this case, since there is no initial payment, the response will focus on the recurrence data that is awaiting the customer’s consent. The pix_rec_id, the recurrence identifier, will be crucial and is typically communicated via webhook after the consent is confirmed.

Webhooks: The Backbone of Asynchronous Communication

Webhooks are essential for keeping your system updated in real time about changes in the status of a payment or consent. Instead of having your application repeatedly poll PagBrasil’s API, PagBrasil actively sends a notification to a URL you specify in your PagBrasil Dashboard.

Importance of webhooks: They allow your application to react immediately to events such as:

• Payment authorized (to release products/services)
• Recurring consent authorized (to activate a subscription)
• Payment failure or consent rejection

Webhook security and authenticity: It’s crucial to ensure that the webhooks received are genuinely from PagBrasil and have not been tampered with.

Acknowledgement of Receipt: After receiving the webhook, your server should respond to PagBrasil’s request confirming successful receipt (e.g., “Received successfully [timestamp]”). Failure to acknowledge may result in error notifications and retries by PagBrasil.

Checking the Status of Orders and Recurrences via API

While webhooks are the preferred method for status updates, PagBrasil’s API also provides endpoints that allow your application to actively check the status of a specific order or recurrence. This can be useful for reconciliations or in contingency scenarios.

Proper implementation of synchronous response handling, webhook listening and validation, and the ability to query status on demand form a robust foundation for a resilient and reliable integration with PagBrasil’s Automatic Pix.

Use Cases: Practical Application Examples

The flexibility of PagBrasil’s Automatic Pix makes it ideal for a wide range of recurring billing scenarios:

E-commerce with Subscriptions and Subscription Boxes: This business model—ranging from online stores offering subscription boxes (beauty products, food, books, etc.) to scheduled replenishment services (like coffee, vitamins, or pet food) and various clubs (wine, craft beer, collectibles)—finds an efficient solution for managing recurring payments in Automatic Pix.

Typically, the “Initial Payment + Consent” flow is the most suitable, as the customer pays for the first month/box at the time of purchase while also authorizing future charges.

SaaS (Software as a Service), Streaming Services, and Digital Content: Companies that offer access to software, online platforms, or digital content (such as videos, music, courses, or publications) through a subscription model can greatly simplify and modernize their billing processes with Automatic Pix.

The ideal journey will depend on your customer acquisition strategy. For immediate paid access, the “Initial Payment + Consent” flow is the most appropriate, charging the first billing cycle at the time of sign-up. If the company offers a free trial period, the “Consent Only” flow is perfectly suited. In this case, the customer authorizes future Pix charges without an upfront payment, and the first payment is automatically processed once the trial period ends.

Recurring Donations: Non-Governmental Organizations (NGOs) and other institutions that rely on regular financial contributions can streamline the donation process for their supporters using Automatic Pix. This enables the setup of automatic donations, ensuring a more stable revenue stream for the organization. The “Initial Payment + Consent” flow is the most suitable, where the donor makes their first contribution and simultaneously authorizes future ones.

Best Practices for Development and Implementation

A robust integration goes beyond functional code—it involves best practices that ensure security, stability, and a smooth experience for the end user.

Consistent error handling:

Validate all customer data in your application before sending it to PagBrasil’s API. This minimizes basic errors and reduces the chance of rejections. Fields like CPF/CNPJ and state abbreviations have specific formats that must be followed.

Be prepared to handle error messages returned by the API. Implement a detailed logging system for all API requests and responses. This will be invaluable for debugging and auditing. Set up alert mechanisms for critical integration failures, enabling a quick response from your technical team.

Webhook management:

As previously discussed, your server must be prepared for PagBrasil’s webhook retry logic. If your server fails to confirm receipt of a webhook or if there is a connection issue, PagBrasil will attempt to resend the notification. It’s crucial that your system can handle multiple notifications for the same event (by checking whether that status has already been processed) and that it responds correctly to avoid resending loops.

Credential and communication security:

Store your credentials in a highly secure manner, and never expose them on the client side.

Always validate the signature in API responses (such as order or recurrence queries) and, most importantly, in all received webhooks. This ensures the authenticity and integrity of the communication.

User experience (UX):

Keep the user informed throughout the entire process. After the QR code is scanned and consent is given, provide clear feedback on the status of the operation.

If a payment or consent fails, display user-friendly error messages and, if possible, provide guidance on how to proceed.

Handling Specific Scenarios

Some scenarios require special attention during implementation:

Expiration of the Pix for initial payment:

• When using the endpoint for an initial payment with consent, you can set an expiration time for the Pix QR Code using the pix_expiration parameter.
• If this parameter is not provided, the system will use the default value configured in your PagBrasil Dashboard.
• It’s a good practice to clearly inform the end user of the deadline for completing the Pix payment, to prevent the QR Code from expiring before the process is completed.
• The expiration date and time are also returned when querying an order via API.

Recurring charge retries:

• PagBrasil allows retrying failed recurring charges. This process is detailed in Section 7 of the integration documentation and uses the same endpoint: /api/order/add.
• It is crucial that, when retrying a failed recurring charge, you explicitly indicate that it is a retry. This is done by including the parameter pix_rec_retry with the value “1”.
• The absence of this parameter in a retry may lead the customer’s bank to interpret the new charge as an attempt to bypass the agreed consent cycle, potentially resulting in issues.
• PagBrasil sets rules for these retries: a maximum of three attempts is allowed, which must be spaced on different days, occur within 7 days of the original charge date, and always maintain the same amount as the original charge.

By considering these use cases and following the implementation tips, you’ll be better equipped to build an integration with PagBrasil’s Automatic Pix that is not only functional, but robust, secure, and capable of delivering an excellent user experience.

Next Steps: Getting Hands-On

With the knowledge you’ve gained throughout this guide—covering integration journeys, API endpoints, response handling, webhooks, and development best practices—you’re well equipped to begin implementing PagBrasil’s Automatic Pix in your application. Now it’s time to put theory into practice.

1. Refer to the full technical documentation:
   1. This article provided a comprehensive overview, but the full technical documentation is your primary source for all details, including the complete list of parameters, sample responses, CPF/CNPJ validation routines, and updates. You can find the Pix Automático integration documentation and other valuable resources directly in the PagBrasil Dashboard, typically under the “Resources” section.
2. Access the Sandbox environment and obtain your credentials:
   1. The first practical step is to begin the integration in PagBrasil’s Sandbox environment. The integration manual provides the test endpoint URLs.
   2. To authenticate your requests, you will need credentials provided by PagBrasil.
   3. Use this environment to perform all necessary tests, covering the different journeys and scenarios relevant to your application.
3. Contact PagBrasil Support:
   1. During the integration process, it’s natural to have specific questions. PagBrasil’s technical support team is available to assist you. You can reach them via email at support@pagbrasil.com.
   2. Once your integration is complete and thoroughly tested in the Sandbox environment, the next step is to migrate to the Production environment. To do this, you’ll need to request the activation of your production account and will receive the corresponding production URLs. Staying in contact with the PagBrasil team is essential for a smooth go-live process.

Remember: A well-planned and thoroughly tested integration is key to ensuring an efficient and seamless recurring payment operation with Automatic Pix. PagBrasil provides the tools and support you need to make your development journey a success.

Your Recurring Payment Solution—Ready for the Future

Throughout this guide, we’ve explored the integration of PagBrasil’s Automatic Pix via API. From understanding the transformative power of Pix in Brazil’s recurring payments landscape, to the nuances of integration journeys, detailed exploration of endpoints, parameters, and webhooks, as well as practical tips and use cases—our goal has been to equip you, the developer, with the knowledge needed to implement a robust, secure, and flexible payment solution.

PagBrasil’s Automatic Pix integration goes far beyond simply adding another payment method to your system. It represents a leap toward the forefront of payment technology, delivering a seamless, agile experience that aligns with the expectations of today’s users. The unique strengths of our solution—such as the built-in security of API-based transactions, flexible consent journeys that support both upfront payments and trial periods, and the granular control offered by direct integration—are all designed to streamline operations, minimize friction, and ultimately boost both operational efficiency and customer satisfaction.

By choosing PagBrasil’s API, you’re equipping your application—or your clients’—with a powerful tool that automates billing, streamlines subscription management, and ensures a more stable and predictable recurring revenue stream. For developers, this means greater control over the user experience, the flexibility to customize flows, and the ability to deeply integrate payment logic into the core of the business.

The future of recurring payments has arrived—and it’s powered by the speed and convenience of Pix. With PagBrasil’s Automatic Pix, your payment solution won’t just be ready for this future—it will be leading it.

We encourage you to revisit the technical documentation, explore the Sandbox environment, and begin your integration journey. The PagBrasil team is ready to support you every step of the way. Start integrating today and transform how your application handles recurring payments.

If you have any questions, please contact our team.