Credit Card Installments

How installment purchases are captured, synchronized, and delivered through the Pluggy API.

Overview#

This page describes how Pluggy captures, processes, and delivers credit card installment purchase transactions (compras parceladas). The goal is to help product and development teams understand the expected API behavior, the limitations of the Open Finance ecosystem, and the best practices for handling this type of data.

Why is this topic complex?

The Open Finance regulation (Central Bank of Brazil) requires institutions to make installment purchase data available, but it does not specify how that data must be formatted or structured. This leads to different behaviors across banks: some post all installments at once, others create them month by month, and others return only the current installment.

Pluggy is actively mapping the behavior of each institution and working together with the Open Finance ecosystem to push for greater standardization.

Fundamentals: Bills and Transactions#

How credit card transactions arrive via API#

When a user connects a credit card account, Pluggy fetches 12 months of transactions. In the subsequent daily updates, the last 7 days of recent transactions are fetched. For credit cards, there is also a third mechanism: fetching transactions by bill, explained below.

Recent Transactions endpoint vs. Bill endpoint in the Open Finance API#

Pluggy uses the Open Finance API, which has two distinct flows for capturing credit card transactions:

The lifecycle of a card transaction#

Every credit card transaction goes through the following cycle:

1. The transaction appears in the recent transactions with status PENDING and without a billId.
2. When the bill becomes due, Pluggy identifies the new bill and calls the transactions endpoint with that bill's ID.
3. The transactions of that bill start returning with an associated billId and the status changes to POSTED.
4. Pluggy fires a webhook with the updated transactions (status and billId filled in).

PENDING vs POSTED

• PENDING: the transaction belongs to a bill that is still open. It has no billId.
• POSTED: the transaction belongs to a bill that is already due. It has an associated billId.

Warning: when fetching only the last 7 days of updates, an older transaction that moved from PENDING to POSTED may not appear. To capture these changes, it is essential to consume the updated transactions webhook (transaction/updated). See Webhooks.

Installment Behavior by Institution#

The lack of standardization in Open Finance means that each bank returns installments in different ways. Pluggy is mapping the behavior of each institution. Below are the general patterns identified so far.

Pattern A: All installments posted at once#

Some institutions post all installments immediately after the purchase, already in the recent transactions. Each installment appears as a separate transaction.

How Pluggy handles this pattern

• 1st installment: returned with the original transaction date (purchase date).
• Remaining installments: returned with the bill posting date (billPostDate) — which corresponds to the due month of each installment.
• When the bill becomes due: the corresponding installment is updated and receives a billId. Pluggy fires the updated transactions webhook with the new billId.

Pattern B: Installments posted month by month#

Other institutions create installments gradually — a new installment appears each time a bill is closed or becomes due. This is the most common behavior among the major banks.

How Pluggy handles this pattern

Pluggy fetches the transactions of each newly due bill. The installments appear at that moment, already with a billId.

Warning: when querying only the transactions endpoint with a date filter, these older installments may not appear. Use the created transactions webhook (transaction/created) to make sure no installment is missed.

Special behavior: Window between closing and due date#

In some banks, there is a period between the closing of the bill and its due date (typically 7 to 10 days). During this window, new installments may appear — that is, when the bill closes, the bank already generates the next installment for the bill that is not yet due.

This means Pluggy may return, via the created transactions webhook, an installment associated with a bill that exists in the bills endpoint but may not yet be due, only closed. This behavior was identified in at least one bank and may occur in others.

Available Installment Fields#

Each installment purchase transaction may contain the following fields (when returned by the institution):

In addition to the fields above, the Open Finance API returns the billPostDate field (the date the transaction was posted to the bill), which Pluggy uses internally to compose the date field of the installments after the first one. This field is not directly exposed in the Pluggy API response JSON.

Important: absence of a group ID

Currently, Open Finance does not return a unique identifier that groups all installments of the same purchase. This means that, to identify that two transactions belong to the same installment plan, you need to use heuristics based on the available fields (installmentNumber, totalInstallments, totalAmount, merchant name, etc.).

Pluggy is evaluating opening an improvement request with the Open Finance ecosystem to ask for this grouping field.

Operational Limits and Their Impact on Installments#

Open Finance defines call limits per CPF/CNPJ per institution, per month. These limits directly affect the ability to synchronize credit card data, including installments.

Limits relevant for credit cards#

How do these limits affect installments?

The limit of 4 calls/month for historical transactions is the most critical. If a user tries to connect the same account several times (for example, because the connection partially failed), this limit can be reached quickly.

When the limit is reached, the call returns an operational limit error and no new 12-month fetch is possible until the next month.

Warning: the limit is per CPF/CNPJ per institution — not per item or per Pluggy client. If the user has already shared data with another platform in the same month, the limit may already have been partially consumed.

Best practices to avoid exhausting the limit#

• Avoid creating multiple connections with the same CPF/CNPJ for the same bank.
• Implement retry control in the frontend: if the connection failed, guide the user to wait before trying again.
• Use the item status check endpoint (GET /items/{id}) after the connection to verify that all products were successfully retrieved, before requesting a new synchronization.

Webhooks and Installment Updates#

To guarantee that no installment update is missed, it is essential to consume Pluggy's webhooks. Installments can appear or be updated at asynchronous moments, outside the 7-day window of recent transactions.

Relevant events for installment plans#

Warning: deleted and recreated transactions

In rare cases, a bank may stop returning a transaction for 1 to 3 days and then return it again. When this happens, Pluggy removes the transaction and fires transaction/deleted. When it comes back, Pluggy fires transaction/created with a new ID.

This can happen, for example, with weekend transactions or during occasional instabilities at the institution. It is not alarming behavior, but it must be handled on the client side.

Recommendations for Development Teams#

To guarantee installment completeness#

• Always consume the transaction/created and transaction/updated webhooks to capture installments that appear outside the 7-day window.
• Do not rely exclusively on the recent transactions endpoint to build the installment history.
• When identifying a due bill, check whether the transactions of that bill (via the transactions endpoint filtered by billId) match the total amount of the bill — this helps detect missing installments.

To identify installments of the same purchase#

• Use the installmentNumber and totalInstallments fields as the first grouping criterion.
• Complement with totalAmount and merchant name when available.
• Keep in mind that behavior varies by bank: the same set of heuristics may not work for all institutions.
• Follow the per-institution mapping that Pluggy is developing.

To report installment problems#

• Open a ticket with Pluggy support informing: bank, item ID, affected period, and a description of the observed behavior.
• If possible, include evidence from the user (statement or bill) showing the discrepancy — this is required to escalate the case to the financial institution.
• For structural cases (affecting multiple users), flag it directly via Slack with the Pluggy support team for prioritization.

Glossary#

For questions, contact the Support team via Slack.