Links de pagamento, transações e assinaturas

A Cativa tem monetização nativa: você cria um link de pagamento (paywall), compartilha a URL pública, e o comprador paga num checkout hospedado pela própria Cativa. A API pública te dá controle programático sobre esses links, sobre as transações que eles geram e sobre as assinaturas recorrentes resultantes. Este conceito explica o que a API expõe hoje, o que ela não expõe, e qual é o padrão recomendado pra transformar “pagou” em “tem acesso”. Pense no paywall como uma maquininha de cartão pré-configurada: você define o valor e a etiqueta uma vez, e sai distribuindo o link como se passasse a maquininha para cada cliente. Você não constrói a maquininha (o checkout é hospedado pela Cativa); você só configura, compartilha e lê o comprovante.

O checkout em si (capturar cartão, processar o pagamento, tokenizar) não é exposto na API pública nesta fase. A compra acontece sempre pelo link de pagamento hospedado da Cativa, identificado pelo customLink. A API pública serve para:

Criar e gerir os links de pagamento (paywalls).
Ler transações e assinaturas.
Cancelar uma assinatura.
Reagir ao webhook paywall-payment-completed.

Você não constrói o formulário de cartão. Você aponta o comprador pra URL hospedada e reage ao resultado.

O modelo

Paywall (link de pagamento)  ──gera──>  Transação (pagamento)
     │                                        │
     │ customLink público                     │ webhook paywall-payment-completed
     ▼                                        ▼
Checkout hospedado Cativa            Badge concedido ──> acesso liberado
     │
     ▼ (se recorrente)
Assinatura ──> renova ──> nova Transação a cada ciclo

Um paywall é o link de pagamento configurável: preço, descrição, se é cobrança única ou recorrente, e o customLink que forma a URL pública. Cada compra bem-sucedida vira uma transação. Se o paywall for recorrente, a compra também cria uma assinatura, que gera uma nova transação a cada ciclo de cobrança.

Base URL e autenticação

Todas as rotas administrativas usam a API da Cativa com a sua API Key:

https://apis.cativalab.digital/tenant/api/v2

Authorization: Bearer cativa_live_...

A API Key é gerada no Console (Developers > API Keys). Veja Quick Start: API Key. A única rota anônima (sem chave) é a de leitura do link público, usada pela página de checkout pra se renderizar.

Nunca exponha a sua API Key no frontend. As rotas /admin/... são de servidor pra servidor. O comprador só toca a rota pública /monetization/paywalls/public/{customLink}.

Links de pagamento (paywalls)

Rotas administrativas para o ciclo de vida do link. Todos os IDs são ULID.

Ação	Método e rota
Listar links	`GET /admin/monetization/paywalls`
Criar link	`POST /admin/monetization/paywalls`
Ler um link	`GET /admin/monetization/paywalls/{paywallId}`
Atualizar link	`PUT /admin/monetization/paywalls/{paywallId}`
Remover link	`DELETE /admin/monetization/paywalls/{paywallId}`
Estatísticas	`GET /admin/monetization/paywalls/stats`

Do link criado ao acesso liberado

Crie o paywall

POST /admin/monetization/paywalls com nome, valor, customLink e se é recorrente. A resposta traz o id e o customLink.

Compartilhe a URL pública

Monte a URL do checkout hospedado a partir do customLink e entregue ao comprador. O checkout é da Cativa; você não constrói o formulário de cartão.

Reaja à conclusão

Em vez de fazer polling, subscreva o webhook paywall-payment-completed. Ele chega no instante em que o pagamento conclui.

Conceda acesso via badge

Configure o paywall para conceder um badge na conclusão. O badge é o que libera grupo/curso/espaço; o dinheiro (transação) e o acesso (badge) ficam desacoplados.

Criar um link de pagamento

curl -X POST 'https://apis.cativalab.digital/tenant/api/v2/admin/monetization/paywalls' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Curso Premium",
    "description": "Acesso vitalício ao Curso Premium",
    "amount": 197.00,
    "customLink": "curso-premium",
    "recurring": false
  }'

const res = await fetch(
  'https://apis.cativalab.digital/tenant/api/v2/admin/monetization/paywalls',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CATIVA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Curso Premium',
      description: 'Acesso vitalício ao Curso Premium',
      amount: 197.0,
      customLink: 'curso-premium',
      recurring: false
    })
  }
);

if (!res.ok) throw new Error(`Create paywall failed: ${res.status}`);
const paywall = await res.json();

Resposta ilustrativa (o schema autoritativo fica no API Reference, tag Paywall). O customLink retornado é o que forma a URL pública:

{
  "id": "01HQ6PAYWALL1234567890XYZ",
  "name": "Curso Premium",
  "customLink": "curso-premium",
  "price": 197.00,
  "isActive": true
}

O corpo exato do request e da resposta (todos os campos aceitos e retornados) está no API Reference, sob as tags Paywall e Payment. Não assuma nomes de campo a partir dos exemplos acima; consulte a referência.

O customLink é o que forma a URL pública que você compartilha com o comprador. Depois de criado, o link está pronto pra receber pagamentos.

O link público (anônimo)

Uma única rota é pública e não exige API Key. A página de checkout hospedada a consome pra buscar os dados do link (nome, preço, descrição) e se renderizar:

GET /monetization/paywalls/public/{customLink}

Você normalmente não chama essa rota diretamente. Você compartilha a URL do checkout hospedado e deixa a Cativa cuidar do resto. Ela existe caso você queira exibir dados do link fora do checkout padrão (ex: um card de preço no seu site).

Transações (pagamentos)

Toda compra bem-sucedida vira uma transação. Você lê transações pra conciliar, auditar ou reagir a uma compra.

Ação	Método e rota
Listar pagamentos	`GET /admin/monetization/payments`
Ler um pagamento	`GET /admin/monetization/payments/{paymentId}`

Listar pagamentos

curl 'https://apis.cativalab.digital/tenant/api/v2/admin/monetization/payments' \
  -H 'Authorization: Bearer YOUR_API_KEY'

const res = await fetch(
  'https://apis.cativalab.digital/tenant/api/v2/admin/monetization/payments',
  {
    headers: { Authorization: `Bearer ${process.env.CATIVA_API_KEY}` }
  }
);

if (!res.ok) throw new Error(`List payments failed: ${res.status}`);
const payments = await res.json();

Resposta ilustrativa (o schema autoritativo, com paginação e todos os campos, fica no API Reference, tag Payment):

{
  "items": [
    {
      "id": "01HQ7PAYMENT1234567890XYZ",
      "paywallId": "01HQ6PAYWALL1234567890XYZ",
      "status": "confirmed",
      "amount": 197.00,
      "customerEmail": "joao@empresa.com",
      "paidAt": "2026-07-10T13:05:00Z"
    }
  ],
  "total": 1
}

Os filtros de query (paginação, período, status) e o formato da resposta estão no API Reference sob a tag Payment. Não invente parâmetros a partir do exemplo.

Para reagir a um pagamento em tempo real, não fique fazendo polling nessa rota. Subscreva o webhook paywall-payment-completed, que chega no seu servidor no instante da conclusão.

Assinaturas

Um paywall recorrente cria uma assinatura na primeira compra. A assinatura renova sozinha a cada ciclo, gerando uma nova transação por cobrança.

Ação	Método e rota
Listar assinaturas	`GET /admin/monetization/subscriptions`
Estatísticas	`GET /admin/monetization/subscriptions/stats`
Cancelar assinatura	`POST /admin/monetization/subscriptions/{subscriptionId}/cancel`

Cancelar é a única operação de escrita sobre assinatura exposta na API pública. Use quando o cliente pede cancelamento no seu app, ou quando um fluxo externo (chargeback, pedido de suporte) precisa encerrar a recorrência.

O que o cancelamento faz com cobranças já emitidas, o período de graça, e o formato das estatísticas estão no API Reference sob a tag Subscription. O comportamento de acesso pós-cancelamento depende de como você amarrou badge ao paywall (veja abaixo).

Padrão recomendado: de “pagou” para “tem acesso”

A API de monetização registra o dinheiro. Ela não é o mecanismo de acesso. Na Cativa, acesso é sempre governado por badge como permissão. O padrão recomendado é:

Configure o paywall pra conceder um badge na conclusão do pagamento (feito no Console, na configuração do paywall).
O badge está configurado como requisito de acesso ao grupo, curso ou espaço que a compra libera.
Quando o pagamento conclui, o badge é atribuído, o acesso aparece. Quando a assinatura é cancelada e o badge é removido, o acesso some.

Assim você não precisa amarrar acesso manualmente a cada transação. O dinheiro (transação/assinatura) e o acesso (badge) ficam desacoplados, cada um na sua rota. O guia Liberar acesso via compra mostra a arquitetura ponta a ponta, inclusive pra compras feitas em gateways externos. Para reagir a cada pagamento (email de boas-vindas, CRM, analytics), subscreva o webhook paywall-payment-completed.

Erros comuns e dúvidas

O comprador pagou mas não ganhou acesso

A API de monetização registra o dinheiro, não o acesso. Acesso é sempre governado por badge. Confirme que o paywall está configurado para conceder um badge na conclusão e que esse badge é o requisito do grupo/curso. Sem esse laço, a transação existe e o acesso não aparece.

Consigo capturar o cartão pela API pública?

Não nesta fase. O checkout (capturar cartão, processar, tokenizar) não é exposto. A compra acontece sempre pelo link hospedado da Cativa, identificado pelo customLink. A API pública cria/gerencia links, lê transações e assinaturas, e cancela assinatura.

Devo fazer polling em /payments para saber quando alguém paga?

Não. Polling desperdiça chamadas e atrasa a reação. Subscreva o webhook paywall-payment-completed, que chega no seu servidor no instante da conclusão. Use a leitura de transações para conciliação e auditoria, não para reagir em tempo real.

O que acontece com o acesso quando cancelo a assinatura?

Cancelar encerra a recorrência. O que acontece com o acesso depende de como você amarrou o badge: se o cancelamento remove o badge, o acesso some junto. As regras de cobranças já emitidas e período de graça ficam no API Reference, tag Subscription.

Recebi 403 numa rota /admin/...

As rotas /admin/... são servidor pra servidor e exigem uma API Key válida com escopo administrativo. Confira o header Authorization: Bearer cativa_live_... e nunca exponha a chave no frontend. A única rota anônima é a leitura do link público (/monetization/paywalls/public/{customLink}).

Próximos passos

Badges como permissão

Entenda por que acesso na Cativa é governado por badge, e não amarrado direto à transação.

Liberar acesso via compra

Arquitetura ponta a ponta de “compra libera acesso”, inclusive para gateways externos.

Webhook paywall-payment-completed

Reaja no instante da conclusão do pagamento em vez de fazer polling nas transações.

Comece aqui

Conceitos

Guias

Webhooks

Changelog

Links de pagamento, transações e assinaturas

O modelo

Base URL e autenticação

Links de pagamento (paywalls)

Do link criado ao acesso liberado

Criar um link de pagamento

O link público (anônimo)

Transações (pagamentos)

Listar pagamentos

Assinaturas

Padrão recomendado: de “pagou” para “tem acesso”

Erros comuns e dúvidas

Próximos passos

Badges como permissão

Liberar acesso via compra

Webhook paywall-payment-completed

​O modelo

​Base URL e autenticação

​Links de pagamento (paywalls)

​Do link criado ao acesso liberado

​Criar um link de pagamento

​O link público (anônimo)

​Transações (pagamentos)

​Listar pagamentos

​Assinaturas

​Padrão recomendado: de “pagou” para “tem acesso”

​Erros comuns e dúvidas

​Próximos passos

Badges como permissão

Liberar acesso via compra

Webhook paywall-payment-completed

O modelo

Base URL e autenticação

Links de pagamento (paywalls)

Do link criado ao acesso liberado

Criar um link de pagamento

O link público (anônimo)

Transações (pagamentos)

Listar pagamentos

Assinaturas

Padrão recomendado: de “pagou” para “tem acesso”

Erros comuns e dúvidas

Próximos passos