> ## 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. # Links de pagamento, transações e assinaturas > Crie e gerencie links de pagamento hospedados, leia transações e controle assinaturas pela API pública da Cativa. 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: 1. **Criar e gerir** os links de pagamento (paywalls). 2. **Ler** transações e assinaturas. 3. **Cancelar** uma assinatura. 4. **Reagir** ao webhook [`paywall-payment-completed`](/pt-BR/webhooks/events/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](/pt-BR/get-started/quickstart-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](https://github.com/ulid/spec). | 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 `POST /admin/monetization/paywalls` com nome, valor, `customLink` e se é recorrente. A resposta traz o `id` e o `customLink`. 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. Em vez de fazer polling, subscreva o webhook [`paywall-payment-completed`](/pt-BR/webhooks/events/paywall-payment-completed). Ele chega no instante em que o pagamento conclui. 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 ```bash cURL theme={null} 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 }' ``` ```js Node theme={null} 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: ```json theme={null} { "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 ```bash cURL theme={null} curl 'https://apis.cativalab.digital/tenant/api/v2/admin/monetization/payments' \ -H 'Authorization: Bearer YOUR_API_KEY' ``` ```js Node theme={null} 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**): ```json theme={null} { "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`](/pt-BR/webhooks/events/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](/pt-BR/concepts/badges-as-permissions). O padrão recomendado é: 1. Configure o paywall pra **conceder um badge** na conclusão do pagamento (feito no Console, na configuração do paywall). 2. O badge está configurado como requisito de acesso ao grupo, curso ou espaço que a compra libera. 3. 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](/pt-BR/guides/grant-access-via-purchase) 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`](/pt-BR/webhooks/events/paywall-payment-completed). ## Erros comuns e dúvidas 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. 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. Não. Polling desperdiça chamadas e atrasa a reação. Subscreva o webhook [`paywall-payment-completed`](/pt-BR/webhooks/events/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. 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**. 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 Entenda por que acesso na Cativa é governado por badge, e não amarrado direto à transação. Arquitetura ponta a ponta de "compra libera acesso", inclusive para gateways externos. Reaja no instante da conclusão do pagamento em vez de fazer polling nas transações.