A API de Pagamentos recorrentes identifica movimentos de caixa que se repetem — assinaturas, salários, contas de consumo, mensalidades — a partir das transações de um Item. É a base para PFM (gestão de finanças pessoais) e para enriquecer modelos de score com renda e despesas fixas.
Os Pagamentos recorrentes ficam no host único da Malvo: POST https://api.malvo.io/recurring-payments. Não existe um subdomínio enrichment-api — todos os produtos de Inteligência & Enriquecimento são servidos em https://api.malvo.io e autenticados pelo header X-API-KEY.

​
A requisição

Envie apenas o itemId do Item cujas transações serão analisadas.

​
O response

A resposta é um array de padrões recorrentes. Cada padrão tem:
Use o sinal do averageAmount para separar saídas de entradas: a assinatura acima é uma despesa (-39.90) e o salário é uma renda (+7500.00). Some os negativos para estimar despesas fixas mensais e os positivos para estimar renda recorrente.

​
Regras de detecção

Um padrão só é reportado quando satisfaz todos os critérios abaixo: O regularityScore (0–1) reflete o quão regular é a cadência: quanto mais próximas do intervalo mensal exato e mais constante o valor, mais alto o score.
A detecção lê o que a última sincronização do Item coletou e cobre até 12 meses de histórico. Padrões muito novos (menos de 3 ocorrências no período) ainda não aparecem. Re-chame após novos syncs para captar assinaturas recém-iniciadas.

​
Casos de uso

1

PFM (gestão de finanças)

Liste para o usuário todas as assinaturas e contas fixas (averageAmount negativo) e a renda recorrente (positivo). O regularityScore ajuda a destacar os compromissos mais previsíveis.
2

Score e capacidade de pagamento

Use a renda recorrente detectada (salário) e o total de despesas fixas para estimar fôlego financeiro em modelos de crédito.
3

Alertas e antecipação

Com a cadência conhecida, antecipe cobranças futuras e avise o usuário antes do débito.

​
Boas práticas

  • Cheque o sinal, não só o valor: averageAmount define se é despesa ou renda.
  • Use occurrences para auditar: cada id aponta para a transação real que originou o padrão.
  • Re-chame após cada sync do Item para captar novos recorrentes — veja Sincronizar transações e Webhooks.
  • Para enriquecer transações avulsas (sem Item), use a Enrich API; para KPIs agregados, o Item Insights.

​
Próximos passos

Item Insights

KPIs agregados por Item para crédito e segmentação.

Enriquecer transações

Categorize e identifique merchants em transações próprias.

Categorização

O catálogo de categorias usado no enriquecimento.

Referência da API

O grupo Inteligência & Enriquecimento no playground.