PIX Automático (Recorrência)

Configure cobranças recorrentes automáticas para assinaturas, mensalidades e planos.
Resumo Rápido

O PIX Automático permite criar assinaturas recorrentes que cobram automaticamente o cliente em intervalos definidos (mensal, semanal, etc). Ideal para SaaS, academias, clubes de assinatura e serviços recorrentes.

1. Criando uma Assinatura

Use o endpoint POST /api/v1/recurring-subscriptions para criar uma nova assinatura recorrente:

Request Body 
{
  "amount": "99.90",
  "frequency": "monthly",
  "description": "Plano Premium Mensal",
  "start_date": "2026-08-01",
  "customer": {
    "name": "João Silva",
    "email": "joao@exemplo.com",
    "cpf": "123.456.789-00"
  },
  "split": [
    {
      "account_id": "uuid-da-conta",
      "percentage": 100
    }
  ]
}

Parâmetros

Parâmetro Tipo Obrigatório Descrição
amount string Sim Valor da cobrança recorrente
frequency string Sim Frequência: weekly, monthly, yearly
description string Sim Descrição da assinatura
start_date string Sim Data de início (YYYY-MM-DD)
customer object Sim Dados do cliente (name, email, cpf)
split array Não Splits para distribuição do valor

2. Gerenciando Assinaturas

Listar Assinaturas 
GET /api/v1/recurring-subscriptions
Ver Detalhes 
GET /api/v1/recurring-subscriptions/{id}
Pausar 
POST /api/v1/recurring-subscriptions/{id}/pause
Retomar 
POST /api/v1/recurring-subscriptions/{id}/resume
Cancelar 
POST /api/v1/recurring-subscriptions/{id}/cancel
Ver Cobranças 
GET /api/v1/recurring-subscriptions/{id}/charges

3. Ciclo de Vida

1 Criada — Assinatura criada e agendada
2 Ativa — Cobranças ocorrendo normalmente
3 Pausada — Cobranças temporariamente suspensas
4 Cancelada — Assinatura encerrada definitivamente

4. Webhooks

Receba notificações sobre eventos da assinatura:

Evento Descrição
subscription.created Nova assinatura criada
subscription.charged Cobrança realizada com sucesso
subscription.failed Cobrança falhou (saldo insuficiente, etc)
subscription.paused Assinatura pausada
subscription.resumed Assinatura retomada
subscription.cancelled Assinatura cancelada
Anterior: Recebendo PIX Próximo: Enviando PIX