#Pagamento vencido ou esquecido
São dois casos diferentes, com eventos diferentes.
#Caso 1: Pix ou boleto que a pessoa gerou e não pagou
Sequência normal de uma venda não paga:
payment.pending: o Pix ou boleto foi gerado. Serve de lembrete, com o copia-e-cola emdata.object.pix.codeou a linha do boleto embillet.lineebillet.url, e a validade empix.expires_at/billet.expires_at.payment.expired: venceu sem pagar. Fim do lembrete.
O que fazer:
- Em
payment.pending: mande o lembrete somente se não chegou umpayment.approvedcom a mesmadelivery.sale_key. Pix pago em segundos é comum; o lembrete pode chegar depois de a pessoa já ter pago. - Em
payment.expired: pare os lembretes daquela venda e ofereça um novo Pix ou boleto. - Um vencido nunca sobrescreve uma aprovação da mesma venda.
data.object.statuséexpired. - O abandono de carrinho (
checkout.abandoned) é outro aviso, de quem nem chegou a gerar pagamento.
Fluxo de decisão:
async function onPending(evt) {
const key = evt.delivery.sale_key;
if (await wasApproved(key)) return; // já pagou, não cobre
await scheduleReminder(key, evt.data.object.pix?.expires_at);
}
async function onExpired(evt) {
await cancelReminders(evt.delivery.sale_key);
await offerNewPayment(evt.data.object.customer.email);
}
async function onApproved(evt) {
await cancelReminders(evt.delivery.sale_key); // aprovado cancela qualquer lembrete
}
Observações por plataforma:
- A Guru manda também
pix.qrcode_url; a Cakto não. - Na Cakto, com order bump, cada item é um pagamento com o seu próprio Pix.
- Se o Pix expirado de um pedido da Cakto não gerar aviso, fale com o suporte da KB.
#Caso 2: cobrança de assinatura que atrasou
subscription.past_due avisa que a cobrança de uma assinatura da plataforma está em atraso. Traz o link da fatura em invoice_payment_url (quando a plataforma manda), para uma régua de cobrança.
Não tire o acesso aqui. O Business OS dá a tolerância do plano (grace_days) antes de encerrar. Quem decide o fim é o access.ended (com end_reason: "not_renewed") ou, no fluxo de pagamentos, o subscription.ended (só a Guru gera).
Se a pessoa pagar durante a tolerância, vem payment.approved e, no fluxo de acesso, access.renewed: o acesso continua, sem ter sido interrompido.
#Porém
- O estado
past_duepode voltar paraactive(a pessoa pagou). Na Guru, toda volta aactivepode chegar comoactivated; trate o aviso seguinte como a verdade. subscription.paused(pausada) não muda o acesso calculado pela KB. Não tire acesso só por ela.- Não use
occurred_atdopast_duecomo "dia do vencimento": é quando o fato foi registrado.