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

# paywall_payment_completed

> Disparado quando o gateway confirma o pagamento de um paywall — momento ideal para liberar acesso em sistemas externos.

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.

<Note>
  O nome interno do evento (usado nos cadastros de webhook do Console) é `paywall_payment_completed`.
</Note>

## 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`:

```json theme={null}
{
  "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

| Campo        | Tipo   | Descrição                             |
| ------------ | ------ | ------------------------------------- |
| `CustomerId` | GUID   | ID do tenant que originou o evento.   |
| `User`       | object | Dados do comprador.                   |
| `Paywall`    | object | Configuração do paywall que foi pago. |
| `Payment`    | object | Detalhes do pagamento confirmado.     |

#### `User`

| Campo              | Tipo     | Descrição                              |
| ------------------ | -------- | -------------------------------------- |
| `User.Id`          | GUID     | ID do usuário comprador.               |
| `User.Email`       | string   | Email do comprador.                    |
| `User.FirstName`   | string   | Primeiro nome.                         |
| `User.LastName`    | string   | Sobrenome.                             |
| `User.DisplayName` | string   | Nome de exibição.                      |
| `User.Username`    | string   | Nome de usuário.                       |
| `User.CreatedAt`   | ISO 8601 | Quando o usuário foi criado no tenant. |

#### `Paywall`

| Campo                           | Tipo           | Descrição                                                                                                                          |
| ------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `Paywall.Id`                    | GUID           | ID do paywall.                                                                                                                     |
| `Paywall.Name`                  | string         | Nome configurado do paywall.                                                                                                       |
| `Paywall.Description`           | string \| null | Descrição livre, quando informada.                                                                                                 |
| `Paywall.CustomLink`            | string         | Slug usado na URL pública do paywall.                                                                                              |
| `Paywall.FullUrl`               | string \| null | URL pública completa de checkout (`{origem-do-tenant}/pagamento/{CustomLink}`). `null` quando o tenant não tem origem configurada. |
| `Paywall.Price`                 | decimal        | Preço cheio configurado (na moeda do tenant — geralmente BRL).                                                                     |
| `Paywall.DiscountPercentage`    | int            | Percentual de desconto vigente no paywall (0-100).                                                                                 |
| `Paywall.MaxInstallments`       | int            | Número máximo de parcelas permitido pelo paywall.                                                                                  |
| `Paywall.AccessMonths`          | int \| null    | Quantidade de meses de acesso concedidos pela compra. `null` para acesso vitalício.                                                |
| `Paywall.RemoveAfterExpiration` | bool           | Se `true`, o acesso é removido automaticamente quando o `AccessMonths` expira.                                                     |
| `Paywall.ActionType`            | int            | Ação executada após o pagamento (ver tabela abaixo).                                                                               |
| `Paywall.ActionPayload`         | string \| null | Carga associada à `ActionType` — tipicamente um ID (de badge, curso ou grupo) ou JSON, conforme o tipo.                            |
| `Paywall.ImageUrl`              | string \| null | Imagem de capa do paywall, quando configurada.                                                                                     |
| `Paywall.OpeningLink`           | string \| null | Link para onde o usuário é redirecionado após a compra, quando configurado.                                                        |

`Paywall.ActionType` segue o enum:

| Valor | Significado                                                       | `ActionPayload`                 |
| ----- | ----------------------------------------------------------------- | ------------------------------- |
| `0`   | `CreateUserOnly` — apenas registra o usuário, sem conceder acesso | vazio                           |
| `1`   | `AddToCourse` — matricula em um curso                             | `CourseId` (GUID)               |
| `2`   | `GrantBadge` — atribui um badge                                   | `BadgeId` (GUID)                |
| `3`   | `AddToGroup` — adiciona a um grupo                                | `GroupId` (GUID)                |
| `4`   | `AddToCourseAndGrantBadge`                                        | JSON com `CourseId` + `BadgeId` |
| `5`   | `AddToGroupAndGrantBadge`                                         | JSON com `GroupId` + `BadgeId`  |
| `6`   | `None` — nenhuma ação automática                                  | vazio                           |

#### `Payment`

| Campo                   | Tipo     | Descrição                                                                                       |
| ----------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `Payment.PaymentId`     | GUID     | ID do pagamento confirmado.                                                                     |
| `Payment.ValorPago`     | decimal  | Valor efetivamente pago após descontos.                                                         |
| `Payment.ValorOriginal` | decimal  | Valor cheio do paywall antes de descontos.                                                      |
| `Payment.Desconto`      | int      | Percentual de desconto aplicado neste pagamento (0-100).                                        |
| `Payment.Installments`  | int      | Número de parcelas escolhido pelo comprador.                                                    |
| `Payment.TipoPagamento` | string   | Forma de pagamento — valores típicos: `PIX`, `CREDIT_CARD`, `BOLETO`. Normalizado em maiúsculo. |
| `Payment.Gateway`       | string   | Gateway que processou (ex: `Asaas`, `Stripe`). String vazia se não informado.                   |
| `Payment.IdTransacao`   | string   | ID externo da transação no gateway (use para conciliação). String vazia se não informado.       |
| `Payment.CompletedAt`   | ISO 8601 | Momento da confirmação do pagamento.                                                            |

<Note>
  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.
</Note>

## Headers do request

| Header                   | Descrição                                                                                                       |
| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `X-Cativa-Signature`     | Assinatura HMAC-SHA256 do disparo, no formato `t=<unixTs>,v1=<hex>`. **Verifique antes de processar o evento.** |
| `X-Cativa-Execution-Id`  | ID único deste evento. Estável entre retries — use como chave de idempotência.                                  |
| `X-Cativa-Automation-Id` | ID 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](/pt-BR/webhooks/subscribing-and-verifying).

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

<Warning>
  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.
</Warning>

## Eventos relacionados

<CardGroup cols={2}>
  <Card title="user_received_badge" icon="shield-check" href="/pt-BR/webhooks/events/user-received-badge">
    Disparado quando o paywall concede badge — útil para casar a permissão recebida com o pagamento.
  </Card>

  <Card title="user_joined_group" icon="users" href="/pt-BR/webhooks/events/user-joined-group">
    Disparado quando o paywall adiciona o comprador a um grupo (ActionType 3 ou 5).
  </Card>

  <Card title="Cadastrando webhooks" icon="webhook" href="/pt-BR/webhooks/subscribing-and-verifying">
    Como cadastrar listeners, verificar HMAC e lidar com retries.
  </Card>

  <Card title="Webhooks (visão geral)" icon="rectangle-history" href="/pt-BR/concepts/webhooks">
    Por que webhooks, garantias de entrega e formato dos payloads.
  </Card>
</CardGroup>