Compras Parceladas no Cartão de Crédito

Como funciona a captura, sincronização e entrega das parcelas via API Pluggy

Visão Geral

Este documento descreve como a Pluggy captura, processa e entrega as transações de compras parceladas no cartão de crédito. O objetivo é ajudar times de produto e desenvolvimento a entender o comportamento esperado da API, as limitações do ecossistema de Open Finance e as melhores práticas para lidar com esse tipo de dado.

📌

Por que este tema é complexo?

A regulação do Open Finance (Banco Central) define que as instituições devem disponibilizar dados de compras parceladas, mas não especifica como esses dados devem ser formatados ou estruturados. Isso gera comportamentos diferentes entre bancos: alguns lançam todas as parcelas de uma vez, outros as criam mês a mês, outros retornam apenas a parcela atual.

A Pluggy está ativamente mapeando o comportamento de cada instituição e trabalhando em conjunto com o ecossistema do Open Finance para pressionar por uma maior padronização.

Fundamentos: Faturas e Transações

Como as transações de cartão de crédito chegam via API

Quando um usuário conecta uma conta de cartão de crédito, a Pluggy busca 12 meses de transações. Nas atualizações diárias subsequentes, são buscados os últimos 7 dias de transações recentes. Para o cartão de crédito, existe ainda um terceiro mecanismo: a busca de transações por fatura, explicado a seguir.

Endpoint de Transações Recentes vs. Endpoint de Fatura na API do Open Finance

A Pluggy utiliza a API do Open Finance, que possui dois fluxos distintos para capturar transações de cartão de crédito:

O ciclo de vida de uma transação de cartão

Toda transação de cartão de crédito passa pelo seguinte ciclo:

1. A transação aparece nas transações recentes com status PENDING e sem billId.
2. Quando a fatura vence, a Pluggy identifica a nova fatura e chama o endpoint de transações com o ID dessa fatura.
3. As transações daquela fatura passam a retornar com um billId associado e o status muda para POSTED.
4. A Pluggy dispara um webhook com as transações atualizadas (status e billId preenchidos).

📘

PENDING vs POSTED

• PENDING: a transação pertence a uma fatura ainda aberta (em aberto). Não tem billId.
• POSTED: a transação pertence a uma fatura já vencida. Tem um billId associado.

⚠️ Atenção: ao buscar apenas os últimos 7 dias de atualizações, uma transação antiga que passou de PENDING para POSTED pode não aparecer. Para capturar essas mudanças, é essencial consumir o webhook de transações atualizadas (transactions/updated).

Comportamento das Parcelas por Instituição

A falta de padronização no Open Finance faz com que cada banco retorne as parcelas de formas diferentes. A Pluggy está mapeando o comportamento de cada instituição. Abaixo estão os padrões gerais identificados até o momento.

Padrão A: Todas as parcelas lançadas de uma vez

Algumas instituições lançam todas as parcelas imediatamente após a compra, já nas transações recentes. Cada parcela aparece como uma transação separada.

Como a Pluggy trata esse padrão

• 1ª parcela: retorna com a data da transação original (data da compra).
• Demais parcelas: retornam com a data de postagem na fatura (billPostDate) — que corresponde ao mês de vencimento de cada parcela.
• Quando a fatura vence: a parcela correspondente é atualizada e passa a ter um billId. A Pluggy dispara webhook de transações atualizadas com o novo billId.

Padrão B: Parcelas lançadas mês a mês

Outras instituições criam as parcelas gradualmente — uma nova parcela surge a cada vez que uma fatura é fechada ou vence. Esse é o comportamento mais comum entre os principais bancos.

Como a Pluggy trata esse padrão

A Pluggy busca as transações de cada nova fatura vencida. As parcelas surgem nesse momento, já com billId.

⚠️ Atenção: ao consultar apenas o endpoint de transações com filtro de data, essas parcelas mais antigas podem não aparecer. Utilize o webhook de transações criadas (transactions/created) para garantir que nenhuma parcela seja perdida.

Comportamento especial: Janela entre fechamento e vencimento

Em alguns bancos, existe um período entre o fechamento da fatura e o seu vencimento (tipicamente 7 a 10 dias). Nessa janela, novas parcelas podem surgir — ou seja, quando a fatura fecha, o banco já gera a próxima parcela para a fatura que ainda não venceu.

Isso significa que a Pluggy pode retornar, via webhook de transações criadas, uma parcela associada a uma fatura que consta no endpoint de faturas mas pode ainda não estar vencida, apenas fechada. Esse comportamento foi identificado em pelo menos um banco e pode ocorrer em outros.

Campos de Parcelamento Disponíveis

Cada transação de compra parcelada pode conter os seguintes campos (quando retornados pela instituição):

Além dos campos acima, a API do Open Finance retorna o campo billPostDate (data de postagem da transação na fatura), que a Pluggy utiliza internamente para compor o campo date das parcelas subsequentes à primeira. Esse campo não é exposto diretamente no JSON de resposta da API Pluggy.

⚠️

Importante: ausência de um ID de grupo

Atualmente, o Open Finance não retorna um identificador único que agrupe todas as parcelas de uma mesma compra. Isso significa que, para identificar que duas transações fazem parte do mesmo parcelamento, é necessário usar heurísticas baseadas nos campos disponíveis (installmentNumber, totalInstallments, totalAmount, nome do estabelecimento, etc.).

A Pluggy está avaliando abrir um item de melhoria junto ao ecossistema do Open Finance para solicitar esse campo de agrupamento.

Limites Operacionais e Impacto nas Parcelas

O Open Finance define limites de chamadas por CPF/CNPJ por instituição, por mês. Esses limites afetam diretamente a capacidade de sincronizar dados de cartão de crédito, incluindo parcelas.

Limites relevantes para cartão de crédito

⚠️

Como esses limites afetam as parcelas?

O limite de 4 chamadas/mês para transações históricas é o mais crítico. Se um usuário tenta conectar a mesma conta várias vezes (por exemplo, porque a conexão falhou parcialmente), esse limite pode ser atingido rapidamente.

Quando o limite é atingido, a chamada retorna erro de limite operacional e nenhuma nova busca de 12 meses é possível até o próximo mês.

⚠️ Atenção: o limite é por CPF/CNPJ por instituição — não por item ou por cliente Pluggy. Se o usuário já compartilhou dados com outra plataforma no mesmo mês, o limite pode já ter sido parcialmente consumido.

Boas práticas para evitar esgotar o limite

• Evitar criar múltiplas conexões com o mesmo CPF/CNPJ para o mesmo banco.
• Implementar controle de tentativas no frontend: se a conexão falhou, orientar o usuário a aguardar antes de tentar novamente.
• Usar o endpoint de verificação de status do item (GET /item/{id}) após a conexão para checar se todos os produtos foram recuperados com sucesso, antes de solicitar nova sincronização.

Webhooks e Atualizações de Parcelas

Para garantir que nenhuma atualização de parcelamento seja perdida, é essencial consumir os webhooks da Pluggy. As parcelas podem surgir ou ser atualizadas em momentos assíncronos, fora da janela de 7 dias de transações recentes.

Eventos relevantes para parcelamentos

⚠️

Atenção: Transações deletadas e recriadas

Em casos raros, um banco pode deixar de retornar uma transação por 1 a 3 dias e depois retorná-la novamente. Quando isso ocorre, a Pluggy remove a transação e dispara transaction/deleted. Quando ela volta, dispara transaction/created com um novo ID.

Isso pode acontecer, por exemplo, com transações de fim de semana ou em instabilidades pontuais da instituição. Não é um comportamento alarmante, mas deve ser tratado no lado do cliente.

Recomendações para Times de Desenvolvimento

Para garantir a completude das parcelas

• Sempre consumir o webhook de transaction/created e transaction/updated para capturar parcelas que surgem fora da janela de 7 dias.
• Não depender exclusivamente do endpoint de transações recentes para montar o histórico de parcelamentos.
• Ao identificar uma fatura vencida, verificar se as transações dessa fatura (via endpoint de transactions com filtro de billId) batem com o valor total da fatura — isso ajuda a detectar parcelas faltantes.

Para identificar parcelas da mesma compra

• Usar os campos installmentNumber e totalInstallments como primeiro critério de agrupamento.
• Complementar com totalAmount e nome do estabelecimento quando disponíveis.
• Considerar que o comportamento varia por banco: o mesmo conjunto de heurísticas pode não funcionar para todas as instituições.
• Acompanhar o mapeamento por instituição que a Pluggy está desenvolvendo.

Para reportar problemas de parcelamento

• Abrir ticket no suporte da Pluggy informando: banco, ID do item, período afetado e descrição do comportamento observado.
• Se possível, incluir evidência do usuário (extrato ou fatura) mostrando a discrepância — isso é necessário para escalar o caso para a instituição financeira.
• Para casos estruturais (afetando múltiplos usuários), sinalizar diretamente pelo Slack com a equipe de suporte da Pluggy para priorização.

Glossário

Para dúvidas, contate o time de Suporte via Slack.