Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.cativa.digital/llms.txt

Use this file to discover all available pages before exploring further.

Esse evento é disparado assim que o gateway de pagamento (Asaas, Stripe, etc.) confirma um pagamento de paywall. É o momento canônico para sincronizar liberação de acesso em sistemas externos (área de membros, plataforma de cursos legada, ERP), já que internamente o Cativa também usa esse mesmo evento para conceder badge/grupo/curso ao usuário.
O nome interno do evento (usado nos cadastros de webhook do Console) é paywall_payment_completed.

​
Quando dispara

  • Gateway de pagamento (Asaas, Stripe) envia callback de confirmação para o Cativa
  • Pagamento PIX é compensado
  • Cobrança de boleto é compensada
  • Cobrança de cartão de crédito é capturada com sucesso
  • Pagamento manual é marcado como confirmado no admin

​
Quando NÃO dispara

  • Pagamento criado mas ainda pendente (PIX gerado e não pago, boleto não vencido, etc.)
  • Pagamento falho ou cancelado pelo gateway
  • Pagamento estornado / refundado depois de já ter sido confirmado
  • Pagamento sem UserId resolvido (ex: PIX onde o pagador ainda não foi associado a um usuário do tenant) — entrega é pulada
  • Paywall ou pagamento não encontrados no enriquecimento do payload (entrega é pulada)

​
Payload

O payload é serializado em PascalCase e enviado no body do POST com Content-Type: application/json. O payload tem três objetos aninhados — User, Paywall e Payment: 
{
  "CustomerId": "01HQ0ABCDEF1234567890XYZ",
  "User": {
    "Id": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
    "Email": "maria@exemplo.com",
    "FirstName": "Maria",
    "LastName": "Silva",
    "DisplayName": "Maria Silva",
    "Username": "maria.silva",
    "CreatedAt": "2026-04-12T14:32:01Z"
  },
  "Paywall": {
    "Id": "01HQ5PAYWALL1234567890ABC",
    "Name": "Mentoria Premium 2026",
    "Description": "Acesso de 12 meses à mentoria, cursos exclusivos e grupo VIP.",
    "CustomLink": "mentoria-premium-2026",
    "FullUrl": "https://comunidade.exemplo.com/pagamento/mentoria-premium-2026",
    "Price": 1497.00,
    "DiscountPercentage": 10,
    "MaxInstallments": 12,
    "AccessMonths": 12,
    "RemoveAfterExpiration": true,
    "ActionType": 5,
    "ActionPayload": "01HQ4ABCDEF1234567890XYZ",
    "ImageUrl": "https://cdn.cativalab.digital/paywall/01HQ5.../cover.jpg",
    "OpeningLink": "https://comunidade.exemplo.com/boas-vindas-mentoria"
  },
  "Payment": {
    "PaymentId": "01HQ9PAYMENT1234567890XYZ",
    "ValorPago": 1347.30,
    "ValorOriginal": 1497.00,
    "Desconto": 10,
    "Installments": 12,
    "TipoPagamento": "CREDIT_CARD",
    "Gateway": "Asaas",
    "IdTransacao": "pay_5478392a01b2c3d4e5f6",
    "CompletedAt": "2026-05-08T14:32:01Z"
  }
}

​
Campos do payload

​
Raiz

CampoTipoDescrição
CustomerIdGUIDID do tenant que originou o evento.
UserobjectDados do comprador.
PaywallobjectConfiguração do paywall que foi pago.
PaymentobjectDetalhes do pagamento confirmado.

​
User

CampoTipoDescrição
User.IdGUIDID do usuário comprador.
User.EmailstringEmail do comprador.
User.FirstNamestringPrimeiro nome.
User.LastNamestringSobrenome.
User.DisplayNamestringNome de exibição.
User.UsernamestringNome de usuário.
User.CreatedAtISO 8601Quando o usuário foi criado no tenant.

​
Paywall

CampoTipoDescrição
Paywall.IdGUIDID do paywall.
Paywall.NamestringNome configurado do paywall.
Paywall.Descriptionstring | nullDescrição livre, quando informada.
Paywall.CustomLinkstringSlug usado na URL pública do paywall.
Paywall.FullUrlstring | nullURL pública completa de checkout ({origem-do-tenant}/pagamento/{CustomLink}). null quando o tenant não tem origem configurada.
Paywall.PricedecimalPreço cheio configurado (na moeda do tenant — geralmente BRL).
Paywall.DiscountPercentageintPercentual de desconto vigente no paywall (0-100).
Paywall.MaxInstallmentsintNúmero máximo de parcelas permitido pelo paywall.
Paywall.AccessMonthsint | nullQuantidade de meses de acesso concedidos pela compra. null para acesso vitalício.
Paywall.RemoveAfterExpirationboolSe true, o acesso é removido automaticamente quando o AccessMonths expira.
Paywall.ActionTypeintAção executada após o pagamento (ver tabela abaixo).
Paywall.ActionPayloadstring | nullCarga associada à ActionType — tipicamente um ID (de badge, curso ou grupo) ou JSON, conforme o tipo.
Paywall.ImageUrlstring | nullImagem de capa do paywall, quando configurada.
Paywall.OpeningLinkstring | nullLink para onde o usuário é redirecionado após a compra, quando configurado.
Paywall.ActionType segue o enum:
ValorSignificadoActionPayload
0CreateUserOnly — apenas registra o usuário, sem conceder acessovazio
1AddToCourse — matricula em um cursoCourseId (GUID)
2GrantBadge — atribui um badgeBadgeId (GUID)
3AddToGroup — adiciona a um grupoGroupId (GUID)
4AddToCourseAndGrantBadgeJSON com CourseId + BadgeId
5AddToGroupAndGrantBadgeJSON com GroupId + BadgeId
6None — nenhuma ação automáticavazio

​
Payment

CampoTipoDescrição
Payment.PaymentIdGUIDID do pagamento confirmado.
Payment.ValorPagodecimalValor efetivamente pago após descontos.
Payment.ValorOriginaldecimalValor cheio do paywall antes de descontos.
Payment.DescontointPercentual de desconto aplicado neste pagamento (0-100).
Payment.InstallmentsintNúmero de parcelas escolhido pelo comprador.
Payment.TipoPagamentostringForma de pagamento — valores típicos: PIX, CREDIT_CARD, BOLETO. Normalizado em maiúsculo.
Payment.GatewaystringGateway que processou (ex: Asaas, Stripe). String vazia se não informado.
Payment.IdTransacaostringID externo da transação no gateway (use para conciliação). String vazia se não informado.
Payment.CompletedAtISO 8601Momento da confirmação do pagamento.
Os nomes em português (ValorPago, ValorOriginal, Desconto, TipoPagamento, IdTransacao) são herdados da v1 da plataforma e mantidos para compatibilidade com integrações Make/Zapier existentes. Não vão ser renomeados.

​
Headers do request

HeaderDescrição
X-Cativa-SignatureAssinatura HMAC-SHA256 do disparo, no formato t=<unixTs>,v1=<hex>. Verifique antes de processar o evento.
X-Cativa-Execution-IdID único deste evento. Estável entre retries — use como chave de idempotência.
X-Cativa-Automation-IdID do listener configurado no Console (mesmo valor para todos os disparos do mesmo cadastro).
A explicação completa de como verificar X-Cativa-Signature, lidar com retries e garantir idempotência (com exemplos em Node, Python, Go e C#) está em Cadastrando e verificando webhooks.

​
Casos de uso

  • Liberar acesso em plataforma externa — se você ainda hospeda parte do conteúdo fora do Cativa (área de membros legada, Hotmart, Memberkit), use Payment.PaymentId + User.Id para liberar acesso lá assim que o pagamento for confirmado.
  • Conciliação financeira — registrar Payment.IdTransacao + Payment.Gateway + Payment.ValorPago no seu ERP/contabilidade para fechar o caixa por gateway.
  • Disparar email transacional — enviar recibo, NF-e ou boas-vindas de “compra confirmada” usando User.Email, Paywall.Name, Payment.ValorPago e Payment.Installments.
Esse evento dispara uma vez por pagamento confirmado — ele não dispara em renovação automática de assinatura (cobrança recorrente ainda não está em produção). Não trate este evento como gatilho de renovação.

​
Eventos relacionados

user_received_badge

Disparado quando o paywall concede badge — útil para casar a permissão recebida com o pagamento.

user_joined_group

Disparado quando o paywall adiciona o comprador a um grupo (ActionType 3 ou 5).

Cadastrando webhooks

Como cadastrar listeners, verificar HMAC e lidar com retries.

Webhooks (visão geral)

Por que webhooks, garantias de entrega e formato dos payloads.