How to integrate Pix and payments into your system

Integrating Pix and other payments into a system means the system itself creates the charge, receives the payment confirmation and marks it as paid on its own, with nobody checking bank statements. The customer sees a QR code or a card form on screen, pays, and the order, monthly fee or work order changes status automatically.

Pix is Brazil's instant payment system, created and run by the Central Bank of Brazil. Payments are made from the payer's banking app, usually by scanning a QR code, and settle within seconds. This article uses Brazil as its main example, where Pix sits alongside the boleto and credit cards. The payment methods available to you vary by country, but the principles that follow, from gateways and webhooks to recurring billing, reconciliation and security, apply to almost any payment integration.

There are two main paths. The first is to use a payment gateway or payment facilitator, a company that offers Pix, boleto and cards through a single API (an interface that lets systems talk to each other). The second is to integrate directly with the bank or payment institution where the company holds its account, using the Pix API those institutions provide.

A gateway is usually faster to set up and brings several payment methods together. A direct integration tends to give more control over Pix and may have a different cost structure. The choice depends on which payment methods you need, your volume and how much you want to depend on an intermediary.

Gateway or direct integration with the bank

Payment gateway or facilitator

The gateway sits between the company's system and the financial institutions. A single integration gives access to Pix, boleto, credit cards and, in many cases, recurring subscriptions. It also takes care of much of the card security and provides a dashboard for looking up transactions.

Points to watch:

• Fees and payout times vary widely between providers and by payment method. Compare current terms directly with each one.
• In some models, the money passes through the facilitator's account before reaching the company's account.
• Switching gateways later means redoing part of the integration, so it's worth isolating that code within the system.

Direct integration with the bank or payment institution

Pix was created by the Central Bank of Brazil, which also defined an API standard for participating institutions. Because of that, direct integrations follow a similar structure from bank to bank, although each one has its own onboarding and authentication details.

In general, it requires a business account at the institution, API access to be enabled and a digital certificate to authenticate the calls. It makes sense when Pix is your main way of getting paid and you want the money going straight into your own account. For cards, integrating directly with acquirers (the companies that process card transactions for merchants) is more complex and rarely pays off for small and mid-sized businesses.

Pix with dynamic QR codes and automatic confirmation

There are two kinds of Pix QR code. A static one is fixed, can be reused and usually doesn't identify which charge is being paid. It works for donations or a shop counter, but someone has to check the bank statement.

A dynamic one is generated by the system for each charge, with an amount, a unique identifier and, if needed, an expiration date. This is what enables full automation:

1. The system creates the charge through the bank's or gateway's API and receives the QR code and the "copy and paste" code (a text version the payer can paste into their banking app).
2. The customer pays in their banking app.
3. The institution sends a webhook, an automatic notice to an address in your system, reporting that the charge has been paid.
4. The system checks the data, marks the charge as paid and triggers the next step: granting access, issuing the receipt, notifying the team.

The webhook can fail or arrive more than once. A well-built system handles this: it logs every notice, ignores duplicates and periodically checks pending charges so it doesn't rely on the notice alone. The article on system integration with APIs explains webhooks and reprocessing in more detail.

One example is Portal da Igreja, a church management platform built by PERVOX with member and finance management, where tithes are paid by Pix with a QR code. It is one of the company's projects.

Pix Automático for recurring charges

Pix Automático was launched by the Central Bank of Brazil in 2025 for charges that repeat, such as monthly fees, subscriptions and utility bills. Broadly, the customer authorizes once, in their own banking app, that a given company may collect periodic payments. From then on, payments happen according to the authorized rules, and the customer can review or cancel the authorization through their bank.

For the company, it is an alternative to a monthly boleto and to recurring credit card billing. Availability, enrollment requirements and conditions vary between institutions, so confirm with your bank or gateway how the feature works today and what your system needs to implement.

Outside Brazil, recurring billing usually relies on stored cards or on bank debit schemes that vary by country. The same questions apply: how the customer authorizes the charge, how they cancel it and how your system learns about each payment.

Boleto and cards

Boleto

The boleto is a Brazilian bank payment slip with a barcode, which the payer settles through a bank or banking app by the due date. Many business customers in Brazil still require it. The system registers the boleto through the API, sends the document to the customer and receives the payment notification. The difference from Pix is timing: confirmation isn't instant, and your order release rules need to reflect that. Other countries have their own delayed payment methods, such as bank transfers or invoices, and the same principle applies.

Credit cards and tokenization

With cards, the main precaution is to keep card data from passing through the company's server. Gateways offer their own forms or components that send the data straight to them and return a token, a code that represents that card without revealing its number.

The system stores only the token. With it, you can charge the card again, for example in a recurring subscription, without asking the customer for the card every month. Many gateways offer built-in subscription management, with automatic retries when a charge is declined.

Automatic reconciliation

Reconciliation means checking that what was charged matches what landed in the account. Done by hand, it takes hours and leads to errors. With an integration, the system does it on its own:

• Each charge has a unique identifier, linked to the order or customer.
• A confirmed payment is applied to the right record, with no typing.
• Reports cross-check charges, payments, fees and payouts.
• Discrepancies, such as underpayments or duplicate payments, become alerts for the team.

Reconciliation is one of the automations with the clearest return. The guide on how to automate business processes shows how to prioritize this kind of task. In subscription products, it is an essential part of billing, as discussed in how to build a SaaS.

Refunds and failures

Payments are never just the happy path. The system needs to plan for:

• Pix refunds: full or partial, initiated by the company through the API.
• Card refunds and chargebacks: when the cardholder disputes the purchase with their issuing bank, the gateway reports it and the system needs to update the order.
• Expired charges: expired QR codes and boletos should change status and, if appropriate, trigger a new charge.
• Provider instability: if the API doesn't respond, the system should retry without creating duplicate charges.
• Customer notices: confirmation, reminders and failed payments. WhatsApp messages can help, as shown in the article on WhatsApp Business API integration.

Security

Card data is protected by an international security standard, PCI DSS. Storing card numbers, expiration dates or security codes requires proper certification and a level of control that rarely makes sense outside the payments industry. The practical rule is never to store card data in your own system and to use the gateway's tokenization instead.

Other precautions:

• API credentials, keys and certificates are kept in a secure place on the server, never in the source code or in an app installed on a phone.
• The address that receives webhooks must verify where the notice came from before marking anything as paid.
• Access to the gateway and bank dashboards uses two-factor authentication and individual user accounts.
• Payers' personal data falls under data protection law. In Brazil, that is the LGPD (Lei Geral de Proteção de Dados), similar in spirit to Europe's GDPR, as explained in LGPD for websites and software. Elsewhere, check the rules that apply in your country.

A payment integration is only ready when it handles failures well, not just when the first payment goes through.

What to ask the provider

• Which payment methods are available, and what are the current fees and payout times?
• Does the API offer webhooks? How do you verify that a notice is legitimate?
• Is there a test environment to simulate payments, refunds and failures?
• How do subscriptions, recurring payment authorizations such as Pix Automático, and charge retries work?
• Are there reports or a statement API for reconciliation?

Frequently asked questions

Do I need a gateway to accept Pix in my system?

Not necessarily. You can integrate directly with the Pix API of your bank or payment institution. A gateway makes more sense when you also need cards, boleto or subscriptions in one place.

What's the difference between a static and a dynamic QR code?

A static code is fixed and reusable, and doesn't identify the charge. A dynamic code is generated for each charge, with an amount and an identifier, which lets the system confirm the payment automatically.

Can I store a customer's card for future charges?

You can store the token generated by the gateway, not the card data. The token enables recurring charges without the card number ever passing through your system.

How much does it cost to integrate payments?

It depends on how many payment methods are included, how failures are handled, the reconciliation and the business rules involved. Per-transaction fees are set by each provider and should be compared separately.

A system that creates the charge and records the payment on its own frees your team for what matters and reduces cash-handling errors. PERVOX builds software and payment integrations and can help you choose the approach that best fits your volume and the payment methods you accept. We work remotely and can run projects in English. Get in touch to talk about your project.