#Liberar conteúdo no pagamento aprovado
Objetivo: quando alguém paga, ela recebe o acesso (área de membros, grupo, curso) e as boas-vindas, uma vez só.
#Primeiro, escolha UM fluxo
Há dois caminhos para saber que "a pessoa pagou". Escolha um e use só ele para decidir acesso. Misturar os dois faz liberar (ou tirar) duas vezes.
| Fluxo | Evento para liberar | Quando usar |
|---|---|---|
payments | payment.approved | Você só precisa saber do dinheiro entrando e não usa a lógica de assinatura do Business OS. |
kb_access | access.started (e access.trial_converted, access.reactivated, access.renewed) | Recomendado para decidir acesso. O Business OS já resolve a regra (qual pagamento vale, tolerância, reembolso com outro pagamento válido) e manda o fato pronto. |
Quem ouve kb_access deixa a liberação para o access.started e usa o payment.approved só para o financeiro.
#Receita com payment.approved
- Confira a assinatura (guia).
- Ignore se
data.object.is_testfortrue(é teste, veja Testes e quarentena). No pagamento esse campo vem sempre,trueoufalse. - Ignore se o
webhook-idjá foi processado. - Ignore se a
delivery.sale_keyjá foi vista (a mesma venda pode gerar mais de um aviso, e a ordem não é garantida). - Descubra o que foi vendido em
data.object.cataloge mapeie pelooffer_id(id nosso, sempre presente quando a oferta está no catálogo) para o seu curso;product_ideplan_idsão opcionais. Se vier{ "unmapped": true }, o aviso não deveria nem ter chegado (fica em quarentena); trate como erro e avise o suporte da KB. O própriocatalogtambém pode faltar. - Identifique a pessoa por
data.object.customer.email(etax_id,phonequando houver).customeré opcional: se faltar, não libere e avise o suporte da KB. Crie o cadastro se não existir. - Libere o acesso e envie as boas-vindas.
- Registre a
sale_keycomo tratada. - Responda 200.
Pseudocódigo:
async function onPaymentApproved(evt) {
const p = evt.data.object;
if (p.is_test) return; // nunca libere teste
if (await seen(evt.id)) return; // idempotência pelo webhook-id
if (await seenSale(evt.delivery.sale_key)) return;
// catalog é opcional e pode ser { unmapped: true } (sem offer_id): nesses casos não há o que liberar.
const offerId = p.catalog && p.catalog.offer_id;
const course = offerId && COURSE_BY_OFFER[offerId];
if (!course) throw new Error("oferta sem mapeamento: " + JSON.stringify(p.catalog));
const c = p.customer; // customer também é opcional
if (!c || !c.email) throw new Error("pagamento sem e-mail do cliente");
const user = await upsertUser({ email: c.email, name: c.name, phone: c.phone });
await grantAccess(user.id, course);
await sendWelcome(user.email);
await markSale(evt.delivery.sale_key);
}
#Receita com access.started (recomendada)
O access.started sai uma única vez por assinatura (subject.id, um kbs_...) quando o primeiro pagamento válido é ligado. O corpo traz data.object.ends_at (até quando vale) e data.object.plan (o plano).
- Confira assinatura e
webhook-id. Aqui não háis_testpara conferir: o objeto de acesso não tem esse campo, porque venda de teste não gera acesso (a KB a recusa com o motivotest_sale). - Libere até
ends_ate envie as boas-vindas. - Guarde
subject.id+ends_at.
Para o acesso ficar certo ao longo do tempo, ouça também:
access.renewed: atualize o fim (data.object.ends_at; o de antes está emdata.previous.ends_at);access.extended: cortesia ou concessão de tempo, atualize o fim;access.adjusted: o fim recuou, mas a pessoa continua com acesso;access.reactivated: voltou depois de ter acabado, devolva o acesso;access.trial_startedeaccess.trial_converted: se houver período de teste;access.ended: tirar o acesso (veja Tirar acesso).
#Porém
- Recorrência: cada cobrança de um plano recorrente também é um
payment.approved, comsale_keynova. "Boas-vindas uma vez porsale_key" mandaria boas-vindas todo mês. Em plano recorrente, useaccess.started. - Pix pago em segundos: o lembrete
payment.pendingpode chegar depois dopayment.approved. Antes de cobrar, confira se não existe aprovação da mesmasale_key. - Order bump (Cakto): cada item é um pagamento com seu próprio Pix. Um carrinho pode gerar mais de um
payment.approved; usedata.object.itemspara saber o que liberar. - Tempo real: com o tempo real ligado para a sua conta, o
access.startedsai segundos depois do pagamento. Sem ele, vem da varredura diária e pode atrasar até cerca de um dia. Pergunte à KB qual é o seu caso. - Teste de verdade: um e-mail de domínio reservado (como
example.com) faz o aviso viraris_test: true. - Pessoa já cadastrada: use o e-mail em minúsculas e sem espaços para comparar. A mesma pessoa pode comprar com e-mails diferentes; isso é problema de cadastro, não do aviso.
← Entrega, retries e idempotência · Tirar acesso no reembolso ou chargeback →