Doações recorrentes

Uma doação recorrente é uma instrução salva para cobrar o cartão de um doador em uma agenda — tipicamente semanal, quinzenal ou mensal. O cartão é tokenizado pelo nosso gateway, então você nunca lida com um PAN real. Uma vez configurado, as cobranças acontecem automaticamente por um cron diário.

Dois caminhos para configurar

Caminho	Quem dispara	Quando usar
Iniciado pelo admin	Um membro da equipe, usando os dados do cartão do doador	O doador disse pessoalmente e você está inserindo no nome dele
Iniciado pelo visitante	O doador, no formulário público de doação	O doador quer se autoatender de casa

Os dois caminhos produzem a mesma linha de banco em recurring_donations e são processados pelo mesmo job noturno.

Configuração iniciada pelo admin

1. Abra o perfil de membro do doador → aba Doações.
2. Clique na ação de criar recorrência.
3. Preencha:
   • Fundo — para qual categoria cada cobrança vai.
   • Valor — valor por cobrança.
   • Frequência — semanal, quinzenal, mensal.
   • Data de início — quando a primeira cobrança roda.
   • Data de fim (opcional) — deixe em branco para indeterminado.
   • Dados do cartão — número, validade, CVV. Passam pelo nosso gateway e voltam como token.
4. Salve.

A primeira cobrança normalmente roda imediatamente (ou na data de início, se estiver no futuro). As cobranças seguintes rodam à noite até a agenda dizer que não devem mais.

A edge function que alimenta isso é create-recurring-donation-gc — ela tokeniza o cartão via PowerTranz, armazena apenas o token + últimos quatro dígitos + validade no banco e nunca toca no PAN completo além do envio inicial.

Configuração iniciada pelo visitante

Quando um doador visita seu formulário público de doação e seleciona Tornar esta uma doação recorrente, o formulário muda para o modo recorrente:

1. O doador escolhe frequência, valor, fundo, data de início.
2. Os dados do cartão do doador passam por um fluxo de checkout hospedado (Genius Checkout) — ele insere o cartão em uma página hospedada pelo gateway, não pelo GCM.
3. O gateway devolve um token.
4. A edge function start-public-recurring-donation-gc salva a linha de doação recorrente usando esse token.

O doador recebe um e-mail de confirmação e pode gerenciar (cancelar, mudar valor) a doação recorrente entrando na sua conta de membro ou clicando em um link mágico no e-mail de confirmação.

Requisito de cartão on-file

Para cobrar depois sem o doador presente, o cartão precisa ser tokenizado na configuração. Algumas formas de pagamento não podem ser tokenizadas — por exemplo, alguns cartões de débito em certas regiões. O fluxo de configuração surfa um erro "este cartão não pode ser usado para recorrência" nesse caso; o doador deve trocar por outro cartão.

Job de cobrança noturno

A edge function charge-recurring-donations roda uma vez por dia. Para cada doação recorrente cuja next_charge_date chegou, ela:

1. Chama o gateway com o token salvo e o valor.
2. Se a cobrança for bem-sucedida — grava uma linha de doação, avança next_charge_date para a próxima data agendada.
3. Se a cobrança falhar — registra a falha, envia um e-mail ao doador pedindo para atualizar o cartão e tenta novamente na próxima execução noturna por até 5 dias. Após 5 falhas, a doação recorrente é pausada.

INFO

Deliberadamente tentamos de novo em vez de pausar imediatamente — recusas do banco frequentemente são transitórias (saldo insuficiente momentâneo) e se resolvem em um dia.

Visão do doador

Os doadores podem:

• Ver suas doações recorrentes ativas no perfil de membro (se conectados).
• Vê-las no link Gerenciar suas doações do e-mail de confirmação.
• Cancelar a partir de qualquer um dos lugares — o cancelamento é imediato.
• Mudar o valor ou a frequência — produz uma nova linha recorrente e encerra a antiga.

Visão do admin

A página Doações → Recorrentes lista cada doação recorrente do espaço de trabalho. Você pode:

• Filtrar por doador, fundo, status.
• Ver a última data de cobrança e a próxima data de cobrança de cada recorrência.
• Pausar / retomar agendas individuais.
• Cancelar em nome do doador.

Cancelamento

Uma doação recorrente pode ser cancelada por:

• O doador (a partir do link de gerenciamento).
• Um admin (a partir da página de doações recorrentes).
• O sistema, após 5 cobranças falhadas consecutivas.

O cancelamento não estorna cobranças anteriores. Doações passadas permanecem no perfil do doador e nos extratos de fim de ano.

Permissões

Ação	Admin	Tesoureiro	Doador (próprio)
Criar recorrência	sim	sim	sim
Ver lista de recorrências	sim	sim	só as próprias
Editar valor / frequência	sim	sim	só as próprias
Cancelar	sim	sim	só as próprias

Perguntas comuns

E se o cartão expirar? O doador recebe um e-mail uma semana antes do vencimento pedindo para atualizar. Se não atualizar, a próxima cobrança falha e iniciamos o ciclo de tentativas.

Posso estornar uma cobrança recorrente? Sim — abra a linha de doação e clique em estornar. Chamamos process-refund contra o gateway. Estornos aparecem como doação negativa nos extratos de fim de ano.

As agendas recorrentes consideram fuso horário? Sim. Cobramos com base no fuso da sua igreja (definido em Configurações → Organização), não UTC.

Próximos passos

• Formulário de doação online — onde os visitantes se autoatendem.
• Extratos e recibos — visão de fim de ano das doações recorrentes.
• Lance uma campanha de doações — receita que usa doações recorrentes.