RecorrênciaRequer liberação

Como funciona

Cobre seus clientes de forma recorrente por Pix. Você cadastra um plano, assina um cliente nele e a plataforma emite uma cobrança a cada ciclo, envia o Pix por e-mail e dá baixa sozinha quando o cliente paga.

PlanoValor e periodicidade (ex.: R$ 99,90 por mês). Um plano serve a várias assinaturas.
AssinaturaLiga um cliente (nome, e-mail e CPF/CNPJ) a um plano, com início e, se quiser, valor próprio e número de ciclos.
CobrançaUm ciclo: vencimento, valor, status e o Pix. Gerada automaticamente a cada período.

Ciclo de vida de uma cobrança

No dia do vencimento, a partir das 8h (horário de Brasília), a plataforma gera o Pix e envia ao cliente um e-mail com o copia e cola e o link da página de pagamento (pay_url).
A 1ª cobrança sai na hora em que a assinatura é criada (issue_first_charge, padrão true), com vencimento em start_date. Com false, segue a regra acima.
Em aberto, o cliente recebe lembretes em D+1 e D+3. E-mails automáticos só saem entre 8h e 21h.
No dia seguinte ao vencimento ela passa para overdue e continua podendo ser paga.
Se o Pix expirar, a página de pagamento gera um novo quando o cliente a abre.
O pagamento é conciliado sozinho e dispara o webhook recurring_charge.paid.
Plano mensal com vencimento nos dias 29, 30 ou 31: nos meses mais curtos vence no último dia e volta ao dia original depois.

Periodicidades (periodicity)

weekly: Semanal
biweekly: Quinzenal
monthly: Mensal
bimonthly: Bimestral
quarterly: Trimestral
semiannual: Semestral
annual: Anual

Status da assinatura

active: Ativa: gera uma cobrança a cada ciclo.
paused: Pausada: não gera novas cobranças até ser retomada.
cancelled: Cancelada por você.
completed: Concluída: atingiu max_cycles ou end_date.

Status da cobrança

pending: Em aberto: emitida, aguardando pagamento.
overdue: Vencida: passou do vencimento sem pagamento; continua pagável.
paid: Paga: pagamento confirmado.
cancelled: Cancelada por você ou junto com a assinatura.

Regras gerais

Liberação: O recurso precisa ser liberado para a sua conta. Sem isso, as rotas respondem 403 com code: "recurring_billing_disabled". Consulte antes com GET https://api.sancopay.com/api/recurring/access (rota fora do /v1), que devolve { "enabled": true }.
Valores: Número em reais; mínimo 1.00 e máximo 999999.99 por cobrança. Vencimentos em YYYY-MM-DD; as demais datas em ISO 8601.
IDs: Planos, assinaturas e cobranças usam uuid nas rotas e nas respostas. Um id de outra conta responde 404.
Idempotência: Envie reference ao criar planos e assinaturas. Criação nova: 201. reference repetida: 200 com o registro existente e o header Idempotent-Replayed: true.
Permissões: Leitura (GET) exige transactions.view; escrita (POST/PATCH/DELETE) exige payments.pix. A credencial padrão tem as duas.
Respostas: Recurso: o objeto direto. Listas: { "data": [...], "meta": {...} }, com page e per_page (1 a 100, padrão 20).
Erros: Mesmo formato { message, code, errors? } do resto da API. 409 com code: "invalid_state": regra de negócio (ex.: assinatura já cancelada). 429 com code: "too_many_requests": limite de reenvio, com retry_after em segundos.

Webhooks

recurring_charge.created: Cobrança emitida. Com o Pix gerado, data.pix traz copy_paste e transaction_id.
recurring_charge.paid: Pagamento confirmado: libere o ciclo no seu sistema.
recurring_charge.overdue: Venceu sem pagamento (dia seguinte ao vencimento). Continua pagável.
recurring_charge.cancelled: Cancelada por você ou pelo cancelamento da assinatura com cancel_open_charges.
recurring_charge.duplicate_payment: A cobrança já estava paga e outro Pix dela também foi pago; data.duplicate_transaction_id traz a transação excedente.

Payloadrecurring_charge.paid

1{2  "event": "recurring_charge.paid",3  "created_at": "2026-10-01T12:42:31.000000Z",4  "data": {5    "id": "c71d4e8a-2f3b-4a6c-9e15-8b0d7f3a2c96",6    "subscription_id": "3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47",7    "subscription_reference": "ASS-1001",8    "plan_id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",9    "plan_name": "Plano Mensal",10    "cycle_number": 1,11    "due_date": "2026-10-01",12    "amount": 99.9,13    "message": "Plano Mensal",14    "status": "paid",15    "pay_url": "https://app.sancopay.com/cobranca/k3Jd9xQ2mZ7pL4vR8tW1nB6cY0aF5sH2eU9gT4oM",16    "pix": null,17    "paid_at": "2026-10-01T12:42:05.000000Z",18    "paid_transaction_id": 4821,19    "cancelled_at": null,20    "customer": {21      "name": "Maria Souza",22      "email": "[email protected]"23    }24  }25}