Guia de Checkout

Este guia explica como funciona o fluxo de compra na PaysClub e como integrar o checkout em sua aplicação — seja usando o checkout hospedado (mais simples) ou criando sessões via API.

Visão geral do fluxo

Toda compra na PaysClub passa por uma sequência fixa: comprador acessa o checkout, preenche dados, escolhe meio de pagamento, paga e recebe acesso ao produto. O backend cria a order em status pending, dispara a cobrança no gateway de pagamento e só libera o acesso quando o pagamento é confirmado via webhook.

1. Comprador acessa /checkout/[slug]
2. Preenche nome, email, CPF, telefone
3. Seleciona método (PIX, cartão ou boleto)
4. POST /api/checkout/create
   ├─ Cria buyer (se novo) + envia email de acesso
   ├─ Cria order (status: pending)
   └─ Gera cobrança no gateway
5. Comprador paga
6. Gateway envia webhook → confirma pagamento
   ├─ Atualiza order.status = "paid"
   ├─ Cria access (libera produto)
   ├─ Envia email de entrega
   ├─ Processa comissão de afiliado
   └─ Dispara seus webhooks externos
7. Frontend redireciona para /checkout/[slug]/success

Opção 1: Checkout hospedado (recomendado)

A forma mais simples é redirecionar o comprador pro checkout que já vive no domíniocompra.paysclub.com. Não há código a escrever — basta o slug do produto.

https://compra.paysclub.com/checkout/seu-produto-slug

# Com plano específico (produtos com vários planos)
https://compra.paysclub.com/checkout/seu-produto-slug?plan=plan_uuid

# Com cupom pré-aplicado
https://compra.paysclub.com/checkout/seu-produto-slug?coupon=BLACKFRIDAY

# Com link de afiliado (cookie é setado)
https://compra.paysclub.com/checkout/seu-produto-slug?ref=AFFILIATE_CODE

Opção 2: Sessão de checkout via API

Se você quer rastrear carrinho abandonado ou pré-popular o email do comprador antes dele chegar na tela de checkout, crie uma sessão. A API retorna um session_idque pode ser usado pra recuperar o checkout depois.

Criar sessão

curl -X POST https://app.paysclub.com/api/checkout/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "550e8400-e29b-41d4-a716-446655440000",
    "plan_id": "660e8400-e29b-41d4-a716-446655440001",
    "email": "comprador@email.com"
  }'

# Resposta
{
  "session_id": "770e8400-...",
  "session_token": "tok_xyz..."
}

Atualizar dados parciais

Conforme o comprador preenche o formulário, atualize a sessão pra que carrinho abandonado tenha os dados disponíveis no email de recuperação:

curl -X PATCH https://app.paysclub.com/api/checkout/sessions/770e8400-... \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "tok_xyz...",
    "name": "João Silva",
    "cpf": "12345678900",
    "coupon_code": "BLACKFRIDAY"
  }'

Tipos de pagamento por produto

One-time

Produtos com billing=one_time aceitam PIX. A API retorna o QR code + código copia-e-cola. O frontend faz polling em /api/orders/[id]/statusaté detectar paid e redireciona pro success.

Recorrente

Produtos com billing=recurring aceitam PIX, cartão ou boleto. Cartão é cobrado imediatamente — se aprovado, acesso liberado na hora. PIX/boleto seguem o flow assíncrono via webhook.

Tratando o redirect final

Após pagamento confirmado, o frontend padrão redireciona pra/checkout/[slug]/success. Se você precisa redirecionar pro seu próprio domínio, configure success_url nas configurações do produto. O webhookorder.paid chega no seu endpoint configurado mesmo que o comprador feche o navegador.