Pagamentos e Billing

Resumo

O P8W oferece um sistema unificado de checkout e billing em app/User/Controllers/CheckoutController.php e app/Core/Payments/, com suporte a 41+ gateways (Stripe, MercadoPago, PayPal, Pagar.me, PagSeguro, Asaas, Vindi, Revolut, Adyen, Braintree, Worldpay, Binance Pay, PIX, Boleto, cartão, etc.). O admin configura em /admin/settings/billing; o usuário efetua pagamentos em /dashboard/checkout.

Para o portal de billing do usuário (faturamento interno), consulte ../billing-portal.md.

Para quem é (personas)

• Usuário final comprando plano, serviço ou recarga.
• Admin financeiro configurando gateways e dunning.
• Super admin com visão global de receita.
• Revendedor (tenant) com gateway próprio.

O que você pode fazer

Checkout (/dashboard/checkout)

• Selecionar método: PIX, cartão de crédito, boleto, carteira digital,

crypto, pagamento manual.

• Aplicar cupom via /api/checkout/validate-coupon.
• Processar pagamento: /api/checkout/process.
• Acompanhar status: /api/checkout/check-status (polling).

Status do Pagamento (views em checkout/status/)

• success.php — pagamento aprovado.
• pending.php — aguardando confirmação (boleto, PIX).
• canceled.php — cancelado pelo usuário.
• expired.php — expirado (boleto vencido, PIX expirado).
• rejected.php — rejeitado pelo gateway.
• error.php — erro técnico.

APIs de Pagamento

• Gerar PIX: POST /api/payments/generate-pix.
• Processar cartão: POST /api/payments/process-card.
• Gerar boleto: POST /api/payments/generate-boleto.
• Pagamento manual: POST /api/payments/manual.
• Consultar status: GET /api/payments/check-status/{id}.

Gerenciamento de Faturas (tab invoices)

• Listar faturas em /dashboard/invoices.
• Ver fatura: GET /api/invoices/{id}.
• Baixar PDF: GET /api/invoices/{id}/pdf.
• Reenvio por email (via reemissão no admin).

Extrato de Transações (tab transactions)

• Listar pagamentos: /dashboard/payments.
• Extrato completo: /dashboard/transactions.

Preferência de Gateway

• Salvar gateway preferido via

POST /api/user/payment-gateway-preference.

Administração (/admin/settings/billing)

• Gateways: configurar credenciais (gateways.php).
• Faturas: emissão, reemissão, cancelamento (invoices.php).
• Pagamentos: ver lista, detalhes (payments.php).
• Dunning: fluxo de cobrança para inadimplentes (dunning.php).
• Uso/AI Costs: usage.php, ai-costs.php.

Como acessar

Como usuário

1. Escolha plano ou produto → redireciona para /dashboard/checkout.
2. Confirme valor, aplique cupom se houver.
3. Selecione método de pagamento.
4. Finalize.
5. Acompanhe em /dashboard/payments ou /dashboard/invoices.

Como admin

1. Acesse /admin/settings/billing.
2. Escolha aba: Gateways, Faturas, Pagamentos, Dunning, Uso, Custos AI.

Tutoriais

Pagar com PIX

Objetivo: Realizar compra rápida via PIX.

Passos:

1. Em /dashboard/checkout, selecione PIX.
2. Clique em Gerar QR Code (/api/payments/generate-pix).
3. Escaneie com app do banco ou copie o código Copia e Cola.
4. Pagamento confirmado via webhook em minutos.

Pagar com Cartão de Crédito

Objetivo: Pagar com cartão e opcionalmente salvar.

Passos:

1. Selecione Cartão.
2. Preencha número, validade, CVV, nome.
3. (Opcional) marque Salvar cartão para próximas compras.
4. Clique Finalizar (/api/payments/process-card).

Baixar fatura em PDF

Objetivo: Obter comprovante fiscal.

Passos:

1. Acesse /dashboard/invoices.
2. Clique em Download PDF na fatura desejada.
3. Ou acesse /api/invoices/{id}/pdf.

Integrações

Gateways suportados (lista completa em app/Core/Payments/Providers/)

Webhooks

• Endpoint: POST /api/webhooks/payments/{gateway}.
• Configure a URL no painel do gateway (ex.:

https://seusite.com/api/webhooks/payments/mercadopago).

Orquestração e Fallback

• PaymentOrchestrator e FallbackManager permitem cascata de gateways

(ex.: se Stripe falhar, tenta Adyen).

• Antifraude integrado via app/Core/Payments/Antifraud/.

Perguntas frequentes

Posso pagar no boleto e acessar imediatamente? Não. Boleto demora de 1 a 3 dias úteis. Para acesso instantâneo, use PIX ou cartão.

Como cancelo uma compra já paga? Abra ticket em /dashboard/support solicitando reembolso. A política de reembolso depende do produto/plano.

Meu cartão foi recusado. O que fazer? O sistema tenta fallback automaticamente (quando configurado). Verifique limite, CVV, dados e tente novamente. Persistindo, use outro método.

Onde vejo as taxas cobradas? Cada gateway tem taxa própria. O admin vê custos em /admin/settings/billing/usage.

Posso salvar múltiplos cartões? Sim. Gerenciamento em /dashboard/profile?tab=payments.

Recebo Nota Fiscal? Sim, quando o admin do tenant tem emissão fiscal configurada.

Posso pagar em cripto? Sim. Suportamos BitPay, Coinbase Commerce, Binance Pay e NOWPayments.

O que é dunning? Fluxo automatizado de cobrança para faturas atrasadas (lembretes por email, retry de cartão, suspensão do serviço).

Limitações e políticas

• PCI DSS: cartões processados via tokenização do gateway — P8W nunca

armazena PAN/CVV.

• MercadoPago Secure Fields ativado (cartão nunca toca o servidor P8W).
• Webhooks validam assinatura HMAC por gateway.
• Idempotência nas requisições de processamento (previne cobrança dupla).
• Rate limiting em /api/payments/*.
• Isolamento multi-tenant — pagamentos por tenant_id.

Relacionados

• Planos e Assinatura
• Carteira e Transações
• Workspace e Serviços Contratados
• Billing Portal (plugin)