Business OS · Documentação

#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.

FluxoEvento para liberarQuando usar
paymentspayment.approvedVocê só precisa saber do dinheiro entrando e não usa a lógica de assinatura do Business OS.
kb_accessaccess.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

  1. Confira a assinatura (guia).
  2. Ignore se data.object.is_test for true (é teste, veja Testes e quarentena). No pagamento esse campo vem sempre, true ou false.
  3. Ignore se o webhook-id já foi processado.
  4. Ignore se a delivery.sale_key já foi vista (a mesma venda pode gerar mais de um aviso, e a ordem não é garantida).
  5. Descubra o que foi vendido em data.object.catalog e mapeie pelo offer_id (id nosso, sempre presente quando a oferta está no catálogo) para o seu curso; product_id e plan_id sã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óprio catalog também pode faltar.
  6. Identifique a pessoa por data.object.customer.email (e tax_id, phone quando houver). customer é opcional: se faltar, não libere e avise o suporte da KB. Crie o cadastro se não existir.
  7. Libere o acesso e envie as boas-vindas.
  8. Registre a sale_key como tratada.
  9. 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).

  1. Confira assinatura e webhook-id. Aqui não há is_test para conferir: o objeto de acesso não tem esse campo, porque venda de teste não gera acesso (a KB a recusa com o motivo test_sale).
  2. Libere até ends_at e envie as boas-vindas.
  3. Guarde subject.id + ends_at.

Para o acesso ficar certo ao longo do tempo, ouça também:

#Porém


← Entrega, retries e idempotência  ·  Tirar acesso no reembolso ou chargeback →