convez.ai
SkillIntegração & APIsIntermediário
antoniocostalopes

Pagou PIX Integrator

antoniocostalopes/pagou-pix-integrator

Integre PIX via Pagou.ai em qualquer projeto com 1 comando

Ver no GitHub
BomPluginScore · de 0 a 100

Plugin 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-integrator

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 5 meses
Versão
v3.0.3
Issues abertas
0
Contribuidores
1

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.

Version Claude Code PT-BR

Next.js Laravel WordPress WooCommerce Generic

🚀 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/update via /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-sdk em 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.id e ACK rápido
  • ✅ Endpoints admin para cancelar PIX pendente e estornar (total ou parcial)
  • ✅ Migrations para pagou_pix_transactions e pagou_webhook_events com constraints UNIQUE
  • ✅ Serviço de reconciliação via GET /v2/transactions/:id com 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 o x-request-id da 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.aiEstadoOnde ir se precisas
✅ PIX pay-inImplementado end-to-endEsta Skill
❌ Card payments (Payment Element, 3DS, tokens pgct_)Não implementado, não está no roadmapDocumentação oficial
❌ Subscriptions (recorrência)Não implementado, não está no roadmapDocumentação oficial
❌ Transfers / Pix Out (payout)Não implementado, não está no roadmapDocumentaçã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. Implementa create/get/cancel/refund e dispara webhooks com HMAC válido. Cenários por prefixo de external_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áticaAnalisa package.json, composer.json, wp-config.php, ORM, rotas, auth, fluxo de checkout — sem perguntar
🤝 Human Approval GateAntes de modificar qualquer arquivo, apresenta plano explícito com lista de mudanças
❓ Só 4 perguntasAPI key, modo (webhook/polling), URL pública (se webhook), status internos — tudo o resto é inferido
🔄 Modo configurávelA partir de 2.0.0, escolhes entre webhook (recomendado) ou polling-only (mais simples, sem URL pública)
🏭 Apenas produçãoDesde 3.0.0, a Skill chama sempre https://api.pagou.ai. Para dev local sem cobranças reais, usar tools/pagou-mock/
🔐 HMAC nos webhooksHMAC-SHA256 no header X-Pagou-Signature com comparação em tempo constante; fail-closed em produção
🛡️ Segurança built-inAPI key apenas backend, valores em centavos, sem segredos em logs ou commits
🔁 Idempotência triplaUpsert por external_ref, UNIQUE em event_id, no-regress em status terminais
⚡ Webhook resilienteACK em < 1s, processamento assíncrono em fila, dedup por id de evento
💸 Cancel + RefundEndpoints admin para cancelar PIX pendente e estornar (total ou parcial)
🩹 ReconciliaçãoJob periódico + endpoint admin que recupera estado via GET
🔍 Tracing por requestIdCaptura x-request-id (ou x-pagou-request-id) e loga em toda chamada — propagado em PagouError/PagouException para suporte
🎨 Frontend prontoReact hook + componente, Blade component, padrão universal — todos com prefixo MIME no QR
📈 Observabilidade15 métricas Prometheus/OTel, 8 alert rules, dashboard Grafana pré-configurado
🧪 Mock + tester locaisServidor mock da API Pagou + script de webhook tester com HMAC válido (em tools/)
📊 Score determinístico6 categorias com pesos fixos, total 0–100 com classificação
🌐 5 stacks suportadosNext.js, Laravel, WordPress, WooCommerce, + adapter genérico
📝 PT-BRToda 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  │
└───────────────┘    └───────────────┘    └───────────────┘
FaseO que aconteceSai com
1️⃣ DescobrirLê manifestos, rotas, models, migrations, auth, fluxo de checkout existente≥ 90% do contexto; só faltam os 4 perguntáveis
2️⃣ ConfirmarGera PAGOU_PIX_INTEGRATION_PLAN.md com lista exata de arquivos a criar/modificar, DDL, endpointsAprovação explícita do utilizador
3️⃣ ImplementarAplica o adapter do framework — cliente, serviço, endpoints (criar / cancel / refund / webhook), persistência, frontendCódigo pronto a rodar
4️⃣ TestarGera e executa unit + integration + webhook + e2e (incluindo HMAC e refund)100% verdes
5️⃣ ValidarPercorre 5 checklists com evidência por itemTodos os críticos ✓
6️⃣ PontuarCalcula score 0–100 e gera relatório finalClassificaçã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

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 /p e 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:

#PerguntaDetalhes
1🔑 PAGOU_API_KEYChave de produção da tua conta Pagou
2🔄 Modo de confirmaçãowebhook (recomendado) ou polling — ver detalhes acima
3🔗 URL pública do projetoSó relevante se modo = webhook. Para registar webhook no painel Pagou
4🏷️ Status internosComo 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.

FrameworkAdapterInclui
⚫Next.js (App + Pages Router)frameworks/nextjs.mdPrisma · Vitest · TypeScript · React hook + componente
🔴Laravel (9, 10, 11)frameworks/laravel.mdEloquent · Jobs · Pest/PHPUnit · Blade + Alpine
🔵WordPress (6.0+)frameworks/wordpress.mdPlugin · REST API · wp-cron
🟣WooCommerce (7.0+)frameworks/woocommerce.mdGateway WC · HPOS · meta de pedido
⚪Genéricoframeworks/generic.mdExpress, 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 browserApenas backend, validado por grep negativo
Webhook sem verificaçãoHMAC-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 inicialEstado final só via webhook, polling backend ou GET de reconciliação — nunca pelo retorno síncrono
Valores em reaisSempre em centavos (Pagou v2) — verificado por teste
Esquecer external_refSempre presente — base de idempotência e reconciliação
Webhook handler com lógica pesada inlineACK rápido {"received": true} + processamento assíncrono
Retry de POST em erroReconciliação via GET, não retentativa de criação
Confirmar refund no POSTEsperar webhook transaction.refunded (estorno bancário leva tempo)
QR base64 sem prefixo MIMESempre 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.ts e pagou-pix-reconcile/route.ts em 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 por requestId.


📊 Sistema de score

A Skill termina sempre com um score técnico 0–100 calculado deterministicamente.

Categorias e pesos

CategoriaPeso
⚙️ Configuração15
🏗️ Arquitetura15
💸 PIX20
📡 Webhooks20
🛡️ Segurança15
🩹 Confiabilidade15
Total100

Classificação

FaixaClassificaçãoAção
🟢 95–100Enterprise ReadyLiberar
🟢 90–94Production ReadyLiberar com monitorização extra
🟡 80–89Minor ImprovementsListar gaps e corrigir antes de prod
🟠 70–79Needs ReviewRevisão humana obrigatória
🔴 0–69Not ReadyNã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 fases
  • KNOWLEDGE.md — fonte única da verdade sobre a API Pagou v2

🎬 Roteiros executáveis por fase

📄 Templates de relatórios

✅ Checklists de validação

🔬 Referência interna


📈 Observabilidade

Production-ready desde a v1.2.0 — sem trabalho manual:


🧪 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 de external_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 Docshttps://developer.pagou.ai
📗 OpenAPI v2https://developer.pagou.ai/api-reference/openapi-v2.json
📕 LLMs Full Docshttps://developer.pagou.ai/llms-full.txt
📙 SDK TypeScript@pagouai/api-sdk
🟪 Claude Codehttps://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

Ver o original no GitHub

Bom para

Relacionados