Pagou PIX Integrator
antoniocostalopes/pagou-pix-integrator
Integre PIX via Pagou.ai em qualquer projeto com 1 comando
Ver no GitHubPlugin para Claude Code que integra pagamentos PIX via Pagou.ai em projetos existentes (Next.js, Laravel, WordPress, WooCommerce ou genérico). Realiza descoberta automática do stack, propõe implementação com boas práticas de segurança e auditoria, e entrega cliente HTTP, webhooks com verificação HMAC-SHA256, migrations de banco e reconciliação automática.
Instalação
npx convez-ai antoniocostalopes/pagou-pix-integrator1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Adicionar pagamento PIX a e-commerce existente
- Implementar webhooks de cobrança com verificação de segurança
- Reconciliação automática de transações PIX
- Cancelamento e estorno de pagamentos PIX
Veredito

Ferramenta sólida e bem documentada que reduz significativamente o tempo de integração PIX em múltiplos stacks. Arquitetura defensiva com webhooks auditados, migrations versionadas e reconciliação — adequada para produção. Exige Claude Code ativo e conta Pagou.ai.
README
A tradução para o português deste README ainda está na fila.
💸 Pagou PIX Integrator
Plugin para Claude Code que integra PIX via Pagou.ai em qualquer projeto existente — com descoberta automática, aprovação humana, testes, validação e score técnico.
🚀 Instalação • ⚙️ Como funciona • 🧰 Frameworks • 📊 Sistema de score • 📚 Documentação
⚡ Quick start
Um único comando no terminal:
# macOS / Linux / WSL
git clone https://github.com/antoniocostalopes/pagou-pix-integrator.git ~/.claude/skills/pagou-pix-integrator
# Windows (PowerShell)
git clone https://github.com/antoniocostalopes/pagou-pix-integrator.git "$env:USERPROFILE\.claude\skills\pagou-pix-integrator"
Reinicia o Claude Code, depois em qualquer projeto:
/pagou-pix-integrator
💡 Preferes o sistema nativo de plugins (com
enable/disable/updatevia/plugin)? Vê o caminho alternativo.
🎯 O que é
Pagou PIX Integrator é um plugin do Claude Code que analisa o seu projeto existente e implementa uma integração PIX completa via Pagou.ai, seguindo boas práticas de arquitetura, segurança e auditoria.
Em vez de leres documentação, copiares snippets e adaptares para o teu stack, invocas a Skill: ela descobre o projeto, propõe um plano, esperas pela tua aprovação, e ela entrega:
- ✅ Cliente HTTP autenticado para a API Pagou v2 — preferindo SDK
@pagouai/api-sdkem Node/TS, wrapper manual nos restantes stacks - ✅ Endpoint público de criação de cobrança PIX
- ✅ Webhook handler com verificação HMAC-SHA256, deduplicação por
event.ide ACK rápido - ✅ Endpoints admin para cancelar PIX pendente e estornar (total ou parcial)
- ✅ Migrations para
pagou_pix_transactionsepagou_webhook_eventscom constraints UNIQUE - ✅ Serviço de reconciliação via
GET /v2/transactions/:idcom job de saúde periódico e endpoint admin - ✅ Modo polling-only opcional (opt-out via 5ª pergunta) — background poller + reconcile-late para cenários sem URL pública
- ✅ Frontend snippets (React hook + componente, Blade + Alpine, padrão universal) com prefixo
data:image/png;base64,correto no QR - ✅ Tracing por
requestId— todo cliente HTTP loga ox-request-idda Pagou para troubleshooting - ✅ Testes unit + integration + webhook + e2e
- ✅ Observabilidade — 15 métricas Prometheus/OTel, 8 alert rules, dashboard Grafana
- ✅ 5 relatórios obrigatórios (PLAN antes, REPORT/SCORE/README/TEST depois)
- ✅ Score técnico 0–100 com classificação determinística
📌 Escopo — PIX-only, por design
Esta Skill faz PIX (pay-in) e nada mais. É uma decisão de produto permanente, não um "ainda não".
| Produto Pagou.ai | Estado | Onde ir se precisas |
|---|---|---|
| ✅ PIX pay-in | Implementado end-to-end | Esta Skill |
❌ Card payments (Payment Element, 3DS, tokens pgct_) | Não implementado, não está no roadmap | Documentação oficial |
| ❌ Subscriptions (recorrência) | Não implementado, não está no roadmap | Documentação oficial |
| ❌ Transfers / Pix Out (payout) | Não implementado, não está no roadmap | Documentação oficial |
Porquê PIX-only: foco é vantagem competitiva. Cobrir só PIX bem é mais útil para o público-alvo (developers brasileiros a integrar PIX em projetos existentes) do que cobrir tudo superficialmente. O webhook handler que a Skill gera roteia defensivamente eventos de subscription/transfer (responde 200 {received: true} em vez de 5xx) para que projetos que partilham a URL com outros produtos da Pagou não acumulem retries falhados.
🏭 Produção apenas (desde v3.0.0)
A Skill chama sempre https://api.pagou.ai. Não há sandbox, não há PAGOU_ENV, não há PAGOU_BASE_URL. Decisão consciente para evitar utilizadores acidentalmente em modo sandbox que auto-aprova pagamentos.
Para desenvolvimento local sem cobranças reais, a Skill vem com:
tools/pagou-mock/— servidor Node (zero deps) que simula a API v2 da Pagou. Implementacreate/get/cancel/refunde dispara webhooks com HMAC válido. Cenários por prefixo deexternal_ref(expire-,refuse-,chargeback-,slow-,silent-).tools/webhook-tester/— script Bash que envia eventos com HMAC válido ao teu localhost. Útil para validar dedup e cenários compostos sem ter URL pública.
✨ Features
| 🔍 Descoberta automática | Analisa package.json, composer.json, wp-config.php, ORM, rotas, auth, fluxo de checkout — sem perguntar |
| 🤝 Human Approval Gate | Antes de modificar qualquer arquivo, apresenta plano explícito com lista de mudanças |
| ❓ Só 4 perguntas | API key, modo (webhook/polling), URL pública (se webhook), status internos — tudo o resto é inferido |
| 🔄 Modo configurável | A partir de 2.0.0, escolhes entre webhook (recomendado) ou polling-only (mais simples, sem URL pública) |
| 🏭 Apenas produção | Desde 3.0.0, a Skill chama sempre https://api.pagou.ai. Para dev local sem cobranças reais, usar tools/pagou-mock/ |
| 🔐 HMAC nos webhooks | HMAC-SHA256 no header X-Pagou-Signature com comparação em tempo constante; fail-closed em produção |
| 🛡️ Segurança built-in | API key apenas backend, valores em centavos, sem segredos em logs ou commits |
| 🔁 Idempotência tripla | Upsert por external_ref, UNIQUE em event_id, no-regress em status terminais |
| ⚡ Webhook resiliente | ACK em < 1s, processamento assíncrono em fila, dedup por id de evento |
| 💸 Cancel + Refund | Endpoints admin para cancelar PIX pendente e estornar (total ou parcial) |
| 🩹 Reconciliação | Job periódico + endpoint admin que recupera estado via GET |
🔍 Tracing por requestId | Captura x-request-id (ou x-pagou-request-id) e loga em toda chamada — propagado em PagouError/PagouException para suporte |
| 🎨 Frontend pronto | React hook + componente, Blade component, padrão universal — todos com prefixo MIME no QR |
| 📈 Observabilidade | 15 métricas Prometheus/OTel, 8 alert rules, dashboard Grafana pré-configurado |
| 🧪 Mock + tester locais | Servidor mock da API Pagou + script de webhook tester com HMAC válido (em tools/) |
| 📊 Score determinístico | 6 categorias com pesos fixos, total 0–100 com classificação |
| 🌐 5 stacks suportados | Next.js, Laravel, WordPress, WooCommerce, + adapter genérico |
| 📝 PT-BR | Toda a documentação e relatórios em português brasileiro |
⚙️ Como funciona
A Skill segue um fluxo imutável de 6 fases. Nunca inverte a ordem.
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ 1. Descobrir │───►│ 2. Confirmar │───►│ 3. Implementar│
│ (silencioso) │ │ Human Approval│ │ (código real) │
└───────────────┘ └───────────────┘ └───────────────┘
│
▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ 6. Pontuar │◄───│ 5. Validar │◄───│ 4. Testar │
│ score 0–100 │ │ checklists │ │ unit+int+e2e │
└───────────────┘ └───────────────┘ └───────────────┘
| Fase | O que acontece | Sai com |
|---|---|---|
| 1️⃣ Descobrir | Lê manifestos, rotas, models, migrations, auth, fluxo de checkout existente | ≥ 90% do contexto; só faltam os 4 perguntáveis |
| 2️⃣ Confirmar | Gera PAGOU_PIX_INTEGRATION_PLAN.md com lista exata de arquivos a criar/modificar, DDL, endpoints | Aprovação explícita do utilizador |
| 3️⃣ Implementar | Aplica o adapter do framework — cliente, serviço, endpoints (criar / cancel / refund / webhook), persistência, frontend | Código pronto a rodar |
| 4️⃣ Testar | Gera e executa unit + integration + webhook + e2e (incluindo HMAC e refund) | 100% verdes |
| 5️⃣ Validar | Percorre 5 checklists com evidência por item | Todos os críticos ✓ |
| 6️⃣ Pontuar | Calcula score 0–100 e gera relatório final | Classificação |
🔄 Modo de confirmação — webhook ou polling
Na Fase 2 (Confirmar) a Skill faz 4 perguntas. A 2ª escolhe o caminho principal de confirmação de pagamento:
🥇 Modo webhook (default, recomendado)
Pagou envia transaction.paid em tempo real para /api/webhooks/pagou. Latência ≈ segundos. Caminho oficial recomendado pela Pagou.
- ✅ Robusto contra cliente fechar o browser
- ✅ Apanha chargebacks tardios e refunds manuais sem job adicional
- ✅ Custo de API baixo (1 request por evento real)
- ⚠️ Requer URL pública (
https://...) + 2 min de setup no painel da Pagou para registar o webhook
Quando escolher: integrações de produção sérias, e-commerce com volume, qualquer projeto com chargeback no domínio.
🥈 Modo polling (opt-out consciente)
Sem webhook, sem painel, sem URL pública. Background poller (cada 1 min) pergunta GET /v2/transactions/{id} para transações pending até estado terminal. Job de reconcile-late (cada 15 min) apanha estados pós-pagamento (refunded, chargedback).
- ✅ Sem URL pública nem painel Pagou
- ✅ Funciona em intranet, dev local sem tunnel, ambientes restritos
- ⚠️ Latência ≈ 30s–1min até confirmar
- ⚠️ Custo de API maior (mais GETs)
- ⚠️ Diverge da recomendação oficial Pagou ("Use GET polling only for reconciliation, never as primary flow") — a Skill avisa explicitamente sempre que o modo é escolhido
Quando escolher: MVP, volume baixo (< 100/dia), bens digitais sem chargeback, dev local, ou projetos sem URL pública. O endpoint de webhook é sempre gerado em ambos os modos, permitindo upgrade futuro sem regenerar código.
🚀 Instalação
Pré-requisitos
- Claude Code CLI instalado
- Git no sistema
Caminho recomendado — git clone (1 comando)
Windows (PowerShell)
git clone https://github.com/antoniocostalopes/pagou-pix-integrator.git "$env:USERPROFILE\.claude\skills\pagou-pix-integrator"
macOS / Linux / WSL
git clone https://github.com/antoniocostalopes/pagou-pix-integrator.git ~/.claude/skills/pagou-pix-integrator
Reinicia o Claude Code. A skill fica disponível em qualquer projeto. O Claude Code varre ~/.claude/skills/*/SKILL.md no arranque — o nosso repo tem SKILL.md no root com frontmatter YAML válido.
Atualizar
git -C ~/.claude/skills/pagou-pix-integrator pull
Desinstalar
# Unix
rm -rf ~/.claude/skills/pagou-pix-integrator
# Windows
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\skills\pagou-pix-integrator"
Caminho alternativo — via /plugin marketplace
Se preferes o sistema nativo de plugins do Claude Code (com enable/disable/uninstall/update integrados):
/plugin marketplace add antoniocostalopes/pagou-pix-integrator
/plugin install pagou-pix-integrator@pagou-pix-integrator
São 2 comandos porque o sistema separa fonte (marketplace) de consumo (plugin) — o mesmo padrão dos plugins oficiais (Figma e outros).
📖 Detalhes completos e troubleshooting em INSTALL.md.
💡 Uso
Caminho canónico — slash command
Dentro de qualquer projeto onde queres adicionar PIX, no Claude Code escreve:
/pagou-pix-integrator
💡 Dica de descoberta: escreve apenas
/pe usa o autocomplete do Claude Code. O slash command é o entry point oficial — explícito, sem ambiguidade, e aparece no catálogo de skills disponíveis.
Alternativa — linguagem natural
Se preferires não memorizar o nome do comando, a Skill também é acionada por frases naturais que mencionem a intenção:
"Integra PIX via Pagou.ai neste projeto."
"Adiciona um webhook da Pagou e implementa a cobrança PIX."
"Implementa pagamento PIX aqui."
Em ambos os casos a Skill cuida do resto. Só precisas de 4 informações — tudo o resto é descoberto:
| # | Pergunta | Detalhes |
|---|---|---|
| 1 | 🔑 PAGOU_API_KEY | Chave de produção da tua conta Pagou |
| 2 | 🔄 Modo de confirmação | webhook (recomendado) ou polling — ver detalhes acima |
| 3 | 🔗 URL pública do projeto | Só relevante se modo = webhook. Para registar webhook no painel Pagou |
| 4 | 🏷️ Status internos | Como mapear paid → pago no teu domínio (default em PT-BR sugerido) |
💡 A Skill nunca pergunta framework, banco, ORM, sistema de auth, onde está o checkout, qual a tabela de pedidos — tudo isso é descoberto silenciosamente na Fase 1.
🧰 Frameworks suportados
Cada adapter traz código pronto a copiar, específico para o stack, com cliente HTTP, serviço, endpoints (criar / cancel / refund / webhook com HMAC), migrations, frontend, e testes.
| Framework | Adapter | Inclui | |
|---|---|---|---|
| ⚫ | Next.js (App + Pages Router) | frameworks/nextjs.md | Prisma · Vitest · TypeScript · React hook + componente |
| 🔴 | Laravel (9, 10, 11) | frameworks/laravel.md | Eloquent · Jobs · Pest/PHPUnit · Blade + Alpine |
| 🔵 | WordPress (6.0+) | frameworks/wordpress.md | Plugin · REST API · wp-cron |
| 🟣 | WooCommerce (7.0+) | frameworks/woocommerce.md | Gateway WC · HPOS · meta de pedido |
| ⚪ | Genérico | frameworks/generic.md | Express, FastAPI, Django, Rails, Go, .NET, … |
Não vês o teu stack? O adapter genérico cobre o contrato universal (DDL, pseudocódigo, contratos de endpoint, HMAC verify por linguagem) que adaptas para qualquer linguagem.
🛡️ Princípios não-negociáveis
Encodados em CLAUDE.md e validados em cada checklist:
| 🚫 Anti-padrão | ✅ Como a Skill faz |
|---|---|
PAGOU_API_KEY no browser | Apenas backend, validado por grep negativo |
| Webhook sem verificação | HMAC-SHA256 obrigatório em produção (fail-closed) |
Dedup por data.id (transação) | Dedup por event.id (top-level) — uma transação emite N eventos |
setStatus('paid') após sucesso no POST inicial | Estado final só via webhook, polling backend ou GET de reconciliação — nunca pelo retorno síncrono |
| Valores em reais | Sempre em centavos (Pagou v2) — verificado por teste |
Esquecer external_ref | Sempre presente — base de idempotência e reconciliação |
| Webhook handler com lógica pesada inline | ACK rápido {"received": true} + processamento assíncrono |
Retry de POST em erro | Reconciliação via GET, não retentativa de criação |
| Confirmar refund no POST | Esperar webhook transaction.refunded (estorno bancário leva tempo) |
| QR base64 sem prefixo MIME | Sempre data:image/png;base64, no <img src=...> |
🏗️ Arquitetura — o que é gerado no seu projeto
seu-projeto/
├── src/lib/pagou/ (ou app/Services/Pagou/, plugins/pagou-pix/, etc.)
│ ├── client.ts ← wrapper HTTP autenticado
│ ├── pix.ts ← serviço PIX (criar · consultar · cancel · refund)
│ ├── signature.ts ← verificação HMAC-SHA256 do webhook
│ └── status.ts ← mapeamento Pagou → status interno
│
├── src/hooks/usePagouPix.ts ← hook React (criar · polling · estados)
├── src/components/PixCheckout.tsx ← QR + copia-e-cola + UX completa
│
├── app/api/pagou/pix/route.ts ← endpoint público (criar cobrança)
├── app/api/webhooks/pagou/route.ts ← webhook (HMAC + dedup + ACK rápido)
├── app/api/admin/pagou/transactions/[id]/cancel/route.ts ← admin (cancelar PIX pendente)
├── app/api/admin/pagou/transactions/[id]/refund/route.ts ← admin (estornar total/parcial)
├── app/api/metrics/route.ts ← Prometheus exposition (opcional)
│
├── prisma/migrations/ ← 2 tabelas novas
│ └── add_pagou_pix/
│ ├── pagou_pix_transactions ← UNIQUE external_ref + pagou_transaction_id
│ └── pagou_webhook_events ← UNIQUE event_id (idempotência)
│
├── tests/pagou/ ← 6 suítes
│ ├── status.test.ts (unit)
│ ├── signature.test.ts (HMAC verify + replay rejection)
│ ├── client.test.ts (integration)
│ ├── webhook.test.ts (dedup + processing + invalid sig)
│ ├── refund.test.ts (total + parcial)
│ └── e2e.test.ts (fluxo completo)
│
├── PAGOU_PIX_INTEGRATION_PLAN.md ← gerado ANTES (approval gate)
├── PAGOU_PIX_INTEGRATION_REPORT.md ← gerado DEPOIS
├── PAGOU_PIX_INTEGRATION_SCORE.md ← score 0–100
├── README_PAGOU_PIX.md ← guia operacional
└── TEST_REPORT.md ← resultados dos testes
Diagramas detalhados em docs/architecture.md, docs/payment-flow.md e docs/webhook-flow.md.
💡 Em modo
polling, são adicionados endpoints de cron (app/api/cron/pagou-pix-poll/route.tsepagou-pix-reconcile/route.tsem Next.js; equivalentes nos outros stacks). O endpoint de webhook continua a ser gerado mas o utilizador não regista no painel da Pagou. Em projetos Node/TS, o adapter Next.js apresenta primeiro o caminho SDK (@pagouai/api-sdk, ~25 linhas) e o wrapper manual (~80 linhas) como alternativa documentada para quem precisa de tracing completo porrequestId.
📊 Sistema de score
A Skill termina sempre com um score técnico 0–100 calculado deterministicamente.
Categorias e pesos
| Categoria | Peso |
|---|---|
| ⚙️ Configuração | 15 |
| 🏗️ Arquitetura | 15 |
| 💸 PIX | 20 |
| 📡 Webhooks | 20 |
| 🛡️ Segurança | 15 |
| 🩹 Confiabilidade | 15 |
| Total | 100 |
Classificação
| Faixa | Classificação | Ação |
|---|---|---|
| 🟢 95–100 | Enterprise Ready | Liberar |
| 🟢 90–94 | Production Ready | Liberar com monitorização extra |
| 🟡 80–89 | Minor Improvements | Listar gaps e corrigir antes de prod |
| 🟠 70–79 | Needs Review | Revisão humana obrigatória |
| 🔴 0–69 | Not Ready | Não deploy. Re-trabalhar. |
⚠️ Score abaixo de 90 não vai para produção sem revisão humana.
Algoritmo determinístico em docs/scoring-engine.md.
📚 Documentação
🧠 Como a Skill pensa
SKILL.md— contrato e fluxo (frontmatter YAML invocável)CLAUDE.md— instruções de execução das 6 fasesKNOWLEDGE.md— fonte única da verdade sobre a API Pagou v2
🎬 Roteiros executáveis por fase
prompts/project-discovery.mdprompts/architecture-discovery.mdprompts/missing-data.mdprompts/integration-plan.mdprompts/pix-integration.mdprompts/webhook-integration.mdprompts/reconciliation.mdprompts/validation.mdprompts/scoring.md
📄 Templates de relatórios
templates/PAGOU_PIX_INTEGRATION_PLAN.mdtemplates/PAGOU_PIX_INTEGRATION_REPORT.mdtemplates/PAGOU_PIX_INTEGRATION_SCORE.mdtemplates/README_PAGOU_PIX.mdtemplates/TEST_REPORT.md
✅ Checklists de validação
checklists/security.mdchecklists/webhook.md— inclui validação HMAC obrigatóriachecklists/reconciliation.mdchecklists/validation.mdchecklists/production.md
🔬 Referência interna
docs/architecture.md— visão da Skill e do código geradodocs/payment-flow.md— fluxo end-to-end de uma cobrançadocs/webhook-flow.md— handler, job, idempotênciadocs/scoring-engine.md— algoritmo determinístico do score
📈 Observabilidade
Production-ready desde a v1.2.0 — sem trabalho manual:
docs/observability/metrics.md— 15 métricas Prometheus/OTel com snippets para Node, Laravel, Python, Godocs/observability/prometheus-alerts.yml— 8 regras de alerta prontas (webhook errors, invalid signatures, silence detection, latência, drift de reconciliação)docs/observability/grafana-dashboard.json— dashboard com 9 painéis em 3 linhas (Cobrança · Webhooks · Reconciliação), importável directamente
🧪 Ferramentas para desenvolvimento
Trabalhar localmente sem depender da API real:
tools/pagou-mock/— servidor que simula a API v2 da Pagou (zero dependências, Node 20+). Implementa as 4 rotas (create,get,cancel,refund) e dispara webhooks com HMAC válido. Cenários por prefixo deexternal_ref:expire-,refuse-,chargeback-,slow-,silent-tools/webhook-tester/— script Bash que envia eventos com assinatura HMAC válida para o teu webhook local. Útil para testar dedup e cenários compostos (ex.: refund antes de paid)
🔗 Referências externas
| 📘 Pagou.ai Docs | https://developer.pagou.ai |
| 📗 OpenAPI v2 | https://developer.pagou.ai/api-reference/openapi-v2.json |
| 📕 LLMs Full Docs | https://developer.pagou.ai/llms-full.txt |
| 📙 SDK TypeScript | @pagouai/api-sdk |
| 🟪 Claude Code | https://claude.com/claude-code |
🔒 Segurança
Encontraste uma vulnerabilidade? Não abras issue pública. Reporta de forma responsável via GitHub Security Advisories ou conforme descrito em SECURITY.md. Vemos cada reporte dentro de 48h.
Em escopo: forjar webhooks, vazar segredos, bypass do Approval Gate, SQL injection / XSS / IDOR no código que esta Skill produz. Fora de escopo: vulnerabilidades na API da Pagou propriamente dita.
📅 Changelog
Versão atual: 3.0.3 — refresh completo do README para refletir fielmente o estado da Skill em 3.0.2: nova secção "📌 Escopo — PIX-only, por design" tornando explícito o que está e não está no roadmap; nova secção "🏭 Produção apenas" promovendo tools/pagou-mock/ para dev local; nova secção "🔄 Modo de confirmação — webhook ou polling" explicando claramente a escolha; tracing por requestId adicionado às features e à lista de capacidades; cross-reference no fluxo das 4 perguntas. PATCH — apenas documentação.
Histórico completo em CHANGELOG.md.
Feito com 💸 para a comunidade brasileira de pagamentos
🐛 Reportar bug • ✨ Sugerir feature • 🧰 Pedir adapter • ⭐ Star no GitHub