Parcelas de Cartão de Crédito

Como as compras parceladas são capturadas, sincronizadas e entregues através da API Pluggy.

Visão Geral#

Esta página descreve como a Pluggy captura, processa e entrega transações de compras parceladas com cartão de crédito. O objetivo é ajudar as equipes 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 tópico é complexo?

A regulamentação de Open Finance (Banco Central do Brasil) exige que as instituições disponibilizem dados de compras parceladas, mas não especifica como esses dados devem ser formatados ou estruturados. Isso leva a comportamentos diferentes entre os bancos: alguns postam todas as parcelas de uma vez, outros as criam mês a mês, e outros retornam apenas a parcela atual.

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

Fundamentos: Contas 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, os últimos 7 dias de transações recentes são buscados. Para cartões de crédito, há também um terceiro mecanismo: buscar transações por conta, explicado abaixo.

Endpoint de Transações Recentes vs. Endpoint de Contas na API de Open Finance#

A Pluggy utiliza a API de 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 um billId.
2. Quando a conta vence, a Pluggy identifica a nova conta e chama o endpoint de transações com o ID daquela conta.
3. As transações daquela conta começam 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 conta que ainda está aberta. Não possui billId.
• POSTED: a transação pertence a uma conta que já está vencida. Possui um billId associado.

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

Comportamento das Parcelas por Instituição#

A falta de padronização em Open Finance significa que cada banco retorna parcelas de maneiras diferentes. A Pluggy está mapeando o comportamento de cada instituição. Abaixo estão os padrões gerais identificados até agora.

Padrão A: Todas as parcelas postadas de uma vez#

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

Como a Pluggy lida com esse padrão

• 1ª parcela: retornada com a data da transação original (data da compra).
• Parcelas restantes: retornadas com a data de postagem da conta (billPostDate) — que corresponde ao mês de vencimento de cada parcela.
• Quando a conta vence: a parcela correspondente é atualizada e recebe um billId. A Pluggy dispara o webhook de transações atualizadas com o novo billId.

Padrão B: Parcelas postadas mês a mês#

Outras instituições criam parcelas gradualmente — uma nova parcela aparece cada vez que uma conta é fechada ou vence. Este é o comportamento mais comum entre os principais bancos.

Como a Pluggy lida com esse padrão

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

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

Comportamento especial: Janela entre o fechamento e a data de vencimento#

Em alguns bancos, há um período entre o fechamento da conta e sua data de vencimento (tipicamente de 7 a 10 dias). Durante essa janela, novas parcelas podem aparecer — ou seja, quando a conta fecha, o banco já gera a próxima parcela para a conta que ainda não está vencida.

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

Campos de Parcelas 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 de Open Finance retorna o campo billPostDate (a data em que a transação foi postada na conta), que a Pluggy usa internamente para compor o campo date das parcelas após a primeira. Este campo não é exposto diretamente na resposta JSON 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 da mesma compra. Isso significa que, para identificar que duas transações pertencem ao mesmo plano de parcelas, você precisa usar heurísticas baseadas nos campos disponíveis (installmentNumber, totalInstallments, totalAmount, nome do comerciante, etc.).

A Pluggy está avaliando a abertura de um pedido de melhoria com o ecossistema de Open Finance para solicitar esse campo de agrupamento.

Limites Operacionais e Seu 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ões 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 tentar conectar a mesma conta várias vezes (por exemplo, porque a conexão falhou parcialmente), esse limite pode ser alcançado rapidamente.

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

Aviso: 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.

Melhores práticas para evitar esgotar o limite#

• Evite criar múltiplas conexões com o mesmo CPF/CNPJ para o mesmo banco.
• Implemente controle de tentativas no frontend: se a conexão falhar, oriente o usuário a esperar antes de tentar novamente.
• Use o endpoint de verificação de status do item (GET /items/{id}) após a conexão para verificar se todos os produtos foram recuperados com sucesso, antes de solicitar uma nova sincronização.

Webhooks e Atualizações de Parcelas#

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

Eventos relevantes para planos de parcelas#

Aviso: transações deletadas e recriadas

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

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

Recomendações para Equipes de Desenvolvimento#

Para garantir a completude das parcelas#

• Sempre consuma os webhooks transaction/created e transaction/updated para capturar parcelas que aparecem fora da janela de 7 dias.
• Não confie exclusivamente no endpoint de transações recentes para construir o histórico de parcelas.
• Ao identificar uma conta vencida, verifique se as transações daquela conta (via o endpoint de transações filtrado por billId) correspondem ao valor total da conta — isso ajuda a detectar parcelas faltantes.

Para identificar parcelas da mesma compra#

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

Para relatar problemas de parcelas#

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

Glossário#

Para perguntas, entre em contato com a equipe de Suporte via Slack.